home *** CD-ROM | disk | FTP | other *** search
/ Business Assistant / Business Assistant.iso / acctg / q_pro4 / qp4doc.doc < prev    next >
Text File  |  1989-09-01  |  436KB  |  15,708 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.                 Q N E    I N T E R N A T I O N A L    P R E S E N T S
  10.  
  11.  
  12.  
  13.  
  14.  
  15.                                         TM
  16.                             Q - P R O  4      (Shareware)
  17.  
  18.                                      Version 4.0
  19.  
  20.  
  21.  
  22.           Q-PRO 4 is a fourth generation language and database for IBM PC-
  23.           DOS, Generic MS-DOS, Novell Netware, and all LANs and networks
  24.           that are IBM Netbios compatible. 
  25.  
  26.           Written in assembler, the Q-PRO 4 interpreter is amazingly fast. 
  27.           In fact, screen and file speed are so fast that an ordinary 4.77
  28.           Mhz PC with floppy disks makes a dandy application machine.
  29.            
  30.           Application development is typically 5 to 10 times faster than
  31.           other databases because of Q-PRO 4's advances features.  Some of
  32.           them are:
  33.  
  34.            -   Advanced fourth generation event driven architecture.
  35.            -   "Painted" screens.
  36.            -   Fill in the blanks data entry screens.
  37.            -   Extremely fast B+ tree multikey indexed file handling.
  38.            -   Inherently structured high level complete language syntax
  39.                with: procedures, table lookup, memory and file arrays,
  40.                subroutines, assembly language interface, and data
  41.                dictionary.
  42.            -   Full record and file locking on supported LAN's and
  43.                networks.
  44.            -   No practical limits on File Size, number of files open
  45.                simultaneously, record size, or memory variables.
  46.            -   Optional distribution system and licence.
  47.            -   Optional translator to language C.
  48.  
  49.           Thousands of commercial copies of Q-PRO 4, Version 4.0, are in
  50.           use in the United States and 40 foreign countries (including a
  51.           Japanese Language version) since 1986.  It has been reviewed in
  52.           Data Based Advisor, PC Magazine and others with universal
  53.           acclaim.
  54.  
  55.           We have recovered our development and made a modest profit so we
  56.           have decided to place it into shareware so more people can try
  57.           this extraordinary language. 
  58.  
  59.                                         Release 1.0
  60.                                         Langhorne, Pennsylvania
  61.                                         September 1, 1989
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.      Copyright (C) 1983-1989 QNE International.  All rights reserved.
  70.  
  71.      No part of this manual may be reproduced, transmitted, transcribed, stored
  72.      in a retrieval system, or translated into any language (natural or
  73.      computer), in any form or by any means, except as described in the
  74.      following license, without the prior written permission of QNE
  75.      International.
  76.  
  77.      You are granted a limited license to use the software described in this
  78.      manual.  The software may be used or copied only in accordance with the
  79.      terms of that license, which is described beginning on the next page.
  80.  
  81.      Information in this manual is subject to change without notice and does not
  82.      represent a commitment on the part of QNE International
  83.  
  84.      QNE International may make improvements and/or changes in this manual
  85.      and/or in Q-PRO 4 Test Drive and/or in Q-PRO 4 at any time.
  86.  
  87.      QNE International is a registered trademark, and Q-PRO 4 is a trademark of
  88.      QNE International.
  89.  
  90.      QNE International
  91.      136 Granite Hill Court
  92.      Langhorne, PA 19047
  93.      (215) 968-5966
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.                   T H E   Q - P R O 4   P R O D U C T   F A M I L Y
  102.                   =================================================
  103.  
  104.                                      Version 4.0
  105.                                      -----------
  106.      Q-PRO 4 User's Group (QUG)
  107.      --------------------------
  108.      Join QUG for only $25.00 per year and enjoy the benefits of a bulletin
  109.      board for users with hints, techniques, and public domain Q-PRO 4 software.
  110.  
  111.      Q-PRO 4
  112.      -------
  113.      This is the highly regarded and well reviewed version of the commercially
  114.      successful Q-PRO 4, Version 4.0.  Full system, manual, and 30 days (up to 2
  115.      hours) free telephone support.
  116.  
  117.      Q-PRO 4 Plus
  118.      ------------
  119.      The same as Q-PRO 4 with a six file report generator, dBASE II/III/IV
  120.      inport utility, Lotus import/export utility, custom configuration
  121.      utilities, and 60 days (up to 3 hours) of free telephone support.
  122.  
  123.      Authors LockUp
  124.      --------------
  125.      With this set of utilities, the application developer can encrypt and lock
  126.      the program code.  Purchase of this package includes a non-transferrable,
  127.      unlimited distribution licence.
  128.  
  129.      Q2C
  130.      ---
  131.      This product translates the Q-PRO 4 source code to language C.  It is then
  132.      compiled and linked producing .EXE files.  You can embed function calls and
  133.      C programs in the source code. Includes a non-transferrable, unlimited
  134.      distribution licence.
  135.  
  136.      Q-Query
  137.      -------
  138.      This is a "post-relational" query system designed for developers and
  139.      endusers.
  140.  
  141.                                      Version 5.0
  142.                                      -----------
  143.      Q-PRO 4, Version 5.0 is the gateway to OS2 and UNIX/XENIX.  All version 4.0
  144.      code is upwards compatible to version 5.0.  From there a whole new world of
  145.      hardware and operating systems is available.
  146.  
  147.                                      Version 3.0
  148.                                      -----------
  149.      For you unreconstructed 8 bit users, there is even a version that runs very
  150.      nicely on CP/M and MP/M-80 (Turbodos too!).  Call for information.
  151.  
  152.  
  153.                              Quic Start for the Impatient
  154.                                           3
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.                   Q U I C   S T A R T   for  the  I M P A T I E N T
  163.                   =================================================
  164.  
  165.      For those of you who don't read the documentation except as a last resort,
  166.      this short guide is dedicated.  We also assume that you know exactly what
  167.      you are doing!
  168.  
  169.      Things You Must Do
  170.      ------------------
  171.      1. Unpack the software. The software is in a self unpacking format.  Simply
  172.      log on the target drive and type the name of each furnished .EXE file.
  173.  
  174.      2.  * * * *  LOAD BTSYS.EXE * * * * by typing BTSYS.  If you skip this
  175.      step, you won't be able to read or write data files.
  176.  
  177.      The Minimum
  178.      -----------
  179.      Q-PRO 4 uses a combination of procedural code and "painted" screens.  You
  180.      write the pro-gram and paint the screen with the Binary Workstation editor.
  181.  
  182.      File handling is  multikey indexed sequential, random, or sequential.  Most
  183.      data files are indexed.  Indexed and random files are defined with a File
  184.      Item Description (FID) file.
  185.  
  186.      Getting On With It
  187.      ------------------
  188.      Load BW.EXE, the program editor.  You use BW to:
  189.  
  190.      -    write the programs.  It comes up ready to edit your program code.
  191.           Functions are initiated by pressing function keys.  The menu is shown
  192.           at the bottom of the screen.  
  193.  
  194.           Pressing F10 will scroll forward the functions associated with each
  195.           function key.  Pressing F9 scrolls backwards.
  196.  
  197.        -  develop the screens.  While in BW, press F8 to go to the screen
  198.           editor. Type the labels/prompts on the screen the way you want then to
  199.           be.  Press F1 to bring up a window used to define enterable screens.
  200.           
  201.        -  define the FID files.
  202.  
  203.      Putting It Together
  204.      ===================
  205.  
  206.      Application Overview
  207.      --------------------
  208.      Generally, you develop an application one program (or screen) at a time. 
  209.      Programs can freely "chain" each other into and out of memory.  Registers,
  210.      files and disk I/O buffers remain intact between screens.
  211.  
  212.  
  213.  
  214.                              Quic Start for the Impatient
  215.                                           4
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.      Program Flow of Control
  224.      -----------------------
  225.      Q-PRO 4 is "Event driven" so flow of control is completely different than
  226.      almost every other language.  Control goes back and forth between the
  227.      operator and program.  This is always under the control of the programmer. 
  228.      For example, when the user is entering data on the screen, he has control. 
  229.      When he moves to the next enterable field, usually the programmer has
  230.      control.
  231.  
  232.      Developing Programs
  233.      ------------------
  234.      The sequence of developing a program module is usually:
  235.  
  236.        1. Design the screen and its entry fields.  The screen data entry fields,
  237.           once defined, are the same as defining memory variables, i.e. you can
  238.           interrogate their value, move data into and out of them, etc.
  239.       
  240.           One of the fields to be filled out when defining a screen data entry
  241.           is "PROCEDURE NAME".  If you enter a name here, when the user enters
  242.           the field and then goes to the next field by pressing return or an
  243.           arrow, the named procedure will be executed.
  244.  
  245.       2.  Write the program code.  The program code is organized into PROCEDURES
  246.           or PROC's.  A procedure is initiated with the keyword (not too
  247.           surprisingly) PROC followed by a space and the name of the procedure. 
  248.           PROC names (and all other names) are limited to 10 characters in
  249.           length and MUST begin with an alpha character. (NOTE: Q-PRO 4 treats
  250.           upper and lower case identically.)
  251.  
  252.           PROCS are terminated with either an END or in the case of a "CALLed"
  253.           proc RETURN.  When the proc terminates control reverts to the operator
  254.           in the enterable screen data field that the programmer puts him in. 
  255.           Usually this is the next enterable field, but the programmer has full
  256.           control of this. 
  257.             
  258.       3.  Designing the files.  Usually the primary data file is very similar to
  259.           the fields on the screen.  If this is the case, the Quic FID facility
  260.           can be utilized very effectively.
  261.  
  262.  
  263.       4.  Learning the language.  Look over the included sample programs
  264.           starting with SAMPINS.QNE.  They are profusely commented and
  265.           illustrate some common coding techniques.
  266.  
  267.           Read the Commands Section of the manual to see the breadth of commands
  268.           available.
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.                              Quic Start for the Impatient
  276.                                           5
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.                                  Quic Reference Card
  285.                                  ===================
  286.  
  287.      IBM PC Terminal Keyboard Definitions
  288.  
  289.      Cursor Left . . . . . .  Left Arrow
  290.      Cursor Right. . . . . .  Right Arrow
  291.      Cursor Up . . . . . . .  Up Arrow
  292.      Cursor Down . . . . . .  Down Arrow
  293.      Cursor Home . . . . . .  Home
  294.      Tab       . . . . . . .  Return key
  295.      Back Tab  . . . . . . .  Shift Tab
  296.      Enter Data  . . . . . .  END
  297.      Function 0  . . . . . .  ESC
  298.      Funct 1-9   . . . . . .  F1-F9
  299.      Funct 11-20 . . . . . .  SF1-SF10
  300.      Clear Screen  . . . . .  Control Home
  301.      Clear to End of Line  .  Control End
  302.      Clear to End of Screen   Control Pg Down
  303.      Insert Character. . . .  Insert Key
  304.      Delete Character. . . .  Delete Key
  305.  
  306.  
  307.      COMMAND SYNTAX
  308.      --------------
  309.      Items within braces {} are optional.  Items within angle brackets <> denote
  310.      a class of item, rather than a literal value.  Square brackets [] are
  311.      required where shown.
  312.  
  313.      Field Descriptor Values
  314.      -----------------------
  315.      Space,x   any data
  316.      X         any data, forced to upper case
  317.      a         alphabetic data(A-Z,a-z,blank)
  318.      A         alphabetic data forced to upper case
  319.      m         alphanumeric data (A-Z, a-z, 0-9, blank)
  320.      M         alphanumeric data forced to upper case (A-Z, a-z, 0-9, blank)
  321.      n,N       numeric data (0-9  +  -  .)
  322.      i,I       integer data (0-9  +  -)
  323.      d, D      digit data (0-9)
  324.  
  325.      Field Functions
  326.      ---------------
  327.      =    autoduplicate       ?    invisible field
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.                                  Quic Reference Card
  336.                                         Page 6
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.      Data Elements
  345.      --------------
  346.      Registers"     Numeric:  #N0  to   #N9
  347.                     String:   #S0  to   #S9
  348.                     Boolean:  #B0  to   #B9
  349.                     Error:    #E   Field:    #F
  350.                     Line:     #L   Keyout:   #K
  351.                     Page:     #P
  352.  
  353.      Screen Fields
  354.      -------------
  355.      $FIELD    [<expression>]      $OFFSET   [<screen data field name>]
  356.  
  357.      File Fields
  358.      -----------
  359.      &<file field name>[<file #>]  &<file field name>[<file #>,<index>]
  360.  
  361.      Literals
  362.      --------
  363.      String (". . ." or '. . .')    Numeric (1,37,5 etc.) 
  364.      Control character (@<value>)
  365.  
  366.      Variables
  367.      ---------
  368.      B - Boolean or bit (set(1) or reset(0))
  369.      I - Integer (-2,147,483,648 to 2,147,483,647)
  370.      F - Floating Point (1.7E-308 to 1.7E+308)
  371.      N - Numeric (0-9, decimal point, plus sign)
  372.      X - String (X indicates any data: alphanumeric, symbols, etc.)
  373.      <variable name> <N or X>, <length> {,<dimension>} {,<2nd dimension>}
  374.  
  375.  
  376.      Keyout Values (#K)
  377.      -------------
  378.        0 - Typed out               1 - Tabbed out
  379.        2 - Backtabbed out          3 - Cursor up
  380.        4 - Cursor down             5 - Cursor left
  381.        6 - Cursor right            7 - Enter
  382.        8 - Home                    9 - Any Function key
  383.       10 - Break
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.                                  Quic Reference Card
  396.                                         Page 7
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.                                        Commands
  405.                                        --------
  406.  
  407.      File Handling
  408.      -------------
  409.      BACKSPACE <file#>{:<error>}
  410.      CLOSE {file# or *}{:<error>}
  411.      COPY <file# or *> TO <file# or *> {:<error>}
  412.      ERASE <filename>{:<error>}
  413.      FCOPY <filename>TO<filename>{:<error>}
  414.      FILETYPE <file#>{:<error>}
  415.      FREE <file#>{:<error>}
  416.      FSEAR <file#>{NOADV}AT<condition> {:<error>}
  417.      GET <data or *> FROM <file#> FOR <length>{TRIMMED}{:<error>}
  418.      KEY <file#>USING<key#>{:<error>}
  419.      LRETRY  <retrycount>
  420.      MAKE/OPEN
  421.       sequential out
  422.           <filename>,0,<file#> {:<error>}
  423.       sequential in
  424.           <filename>,1,<file#>{:<error>} 
  425.       SDF out
  426.           <filename>,4,<file#>{:<error>}
  427.       SDF in
  428.           <filename>,5,<file#>{:<error>}
  429.      Random/Indexed 
  430.           <filename>USING<FIDname>{INDEX<indexname>},<file#>, {UNLOCKED} {R/O}  
  431.         {:<error>}
  432.      POSN <file#> TO <record or key> {RELATIVE} {USING<key#>} {DESCENDING}
  433.           {:<error>}
  434.      PUT <data or *> TO <file#>{FOR <length>}{:<error>}
  435.      RCLEAR <file#>{:<error>}
  436.      READ <file#>{NOADV}{:<error>}
  437.      RENAME <oldfilename>,<newfilename> {:<error>}
  438.      RESTART <file#>{TO<position>}{:<error>}
  439.      RLOCK <file#>{:<error>}
  440.      RUNLOCK <file#>{:error}
  441.      SECURE <file#>{:<error>}
  442.      WRITE <file#>{NOADV}{:<error>}
  443.  
  444.      Error Handling
  445.      --------------
  446.      ERROR <error message, register, or variable>
  447.      ERRTRAP {<line#>}
  448.      NCHECK <data>{:<error>}
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.                                  Quic Reference Card
  456.                                         Page 8
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.      Data Formatting
  465.      ---------------
  466.      EDIT <expression>USING<picture>INTO <data>{:<error>}
  467.      CENTER <data>       CURRENCY <string>   LCASE <data>
  468.      LJUST <data>        RJUST <data>        SIZE <data>INTO<data>{TRIMMED}
  469.      UCASE <data>        UNEDIT <data>INTO<data>{:<error>}
  470.  
  471.      Arithmetic
  472.      ----------
  473.      ACCURACY <value>         ADD <data>TO<data>{GIVING <data>}
  474.      CALC <data>=<expression> MUL <data>TIMES<data>{GIVING <data>}
  475.      ROUND <expression>BY<expression>INTO <data>
  476.      SUB <data>FROM<data>{GIVING <data>}
  477.  
  478.  
  479.      Logical
  480.      -------
  481.      RESET <Boolean register or variable>    SET <Boolean register or variable>
  482.  
  483.      Control Transfer
  484.      ----------------
  485.      BEGIN {WHILE/UNTIL/IF <condition>}
  486.      ELSE {IF<condition>}
  487.      ENDBEGIN {WHILE/UNTIL <condition>}
  488.      BROFF     BRON
  489.      CALL <procedure>    CALL <table[index]>
  490.      CHAIN <filename>{:error}
  491.      END
  492.      FOR <index>=<expression>TO<expression>BY<expression>
  493.      ENDFOR <index>
  494.      GOTO <label>        GOTO <table[index]>
  495.      RETURN
  496.  
  497.      Conditional
  498.      -----------
  499.      IF<condition>{THEN}<statement>
  500.  
  501.      Screen Control
  502.      --------------
  503.      CLEAR <field or *>            CURSOR <row>,<column>
  504.      BUFFER <expression>           FILL <character>
  505.      PRINT <data>{,<data> . . .}   HELP <screen>{,<screen>}{:<error>}
  506.      HOME           HOMECLEAR      HOFF      HON
  507.      LOCK <field>   NEXT <field>
  508.      RESUME
  509.      UNLOCK <field or *>
  510.  
  511.  
  512.  
  513.  
  514.  
  515.                                  Quic Reference Card
  516.                                         Page 9
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.      Data Movement
  525.      -------------
  526.      CONCAT <data>{[<start>,<length or *>] } {TRIMMED} +<data>{[<start>,<length
  527.             or *>]} {TRIMMED} +.  .  .  . INTO <data>{[<start or *>]} {TRIMMED}
  528.      MOVE <data> {[<start>,<length or *>]} TO <data> { [<start or *>]} {TRIMMED}
  529.  
  530.      Table Management
  531.      ----------------
  532.      TABLE <table name>
  533.      TSEAR <table> AT <key>{,<data>, <data>}{:<error>}
  534.      ASEAR <array name> {DOWN} USING <index> AT <condition> {:<error>}
  535.  
  536.      Date Handling
  537.      -------------
  538.      JDPACK <string> INTO <data>        JDUNPACK <data> INTO <string>
  539.      GETDATE <data>                     SETDATE <data>
  540.  
  541.      Operating System Interface
  542.      FORMLOAD            NOFORMLOAD
  543.      SYSTEM              LPDETACH
  544.      HOST <host system> {:<error>} 
  545.      RUN <file name> USING <parameter>{NOPAUSE} {NORETURN} {RELOAD} <filename>}
  546.          {CONTINUE} {:<error>}
  547.  
  548.      Miscellaneous
  549.      -------------
  550.      *    comment
  551.      SYSMODE BTAB <SET or RESET>
  552.              LPCHK <SET or RESET>
  553.      PRINTSCN {:<error>} 
  554.      INSTR <substring>{TRIMMED},<string>{TRIMMED},<result>
  555.  
  556.      Debugging
  557.      ---------
  558.      NOTRACE        TRACE          DEBUG
  559.       
  560.      Assembler Interface
  561.      -------------------
  562.      DEFSEG {<address>}
  563.      EXEC <input  string> {,<output  string>} {:<error>}
  564.      LOAD <filename>,<address>{:<error>}
  565.      PEEK <address>, <length>, <data>   POKE <address>, <data>
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.                                  Quic Reference Card
  576.                                        Page 10
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.                                   SPECIAL PROCEDURES
  585.                                   ==================
  586.  
  587.      PROC BREAK          PROC ENTER          PROC ERROR
  588.      PROC  KEY<N>        PROC LOAD
  589.  
  590.  
  591.                                       FUNCTIONS
  592.                                       ---------
  593.  
  594.      ASCII Value:   $ASC()         e to Power:    $ETOX()
  595.      Scrn.Field No.:$FIELD()       Integer Value: $INT()
  596.      Top of memory: $MEMEND()      Natural Log:   $LN()
  597.      Screen Offset: $OFFSET()
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.                                  Quic Reference Card
  636.                                        Page 11
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.                                   Table of Contents
  646.  
  647.  
  648.      SINGLE COPY SOFTWARE LICENSE  . . . . . . . . . . . . . . . . . . . . .   1
  649.  
  650.      LIMITED LICENSE TO COPY . . . . . . . . . . . . . . . . . . . . . . . .   3
  651.  
  652.      I N T R O D U C I N G   Q-PRO 4  T E S T   D R I V E  . . . . . . . . .   4
  653.           Purchasing Q-PRO 4 . . . . . . . . . . . . . . . . . . . . . . . .   5
  654.  
  655.      Q-PRO 4  O V E R V I E W  . . . . . . . . . . . . . . . . . . . . . . .   7
  656.  
  657.      Q - P R O 4   T U T O R I A L . . . . . . . . . . . . . . . . . . . . .  10
  658.           Installing Q-PRO 4 . . . . . . . . . . . . . . . . . . . . . . . .  11
  659.           Example Program  . . . . . . . . . . . . . . . . . . . . . . . . .  11
  660.                Load Binary WorkStation . . . . . . . . . . . . . . . . . . .  11
  661.                STEP 1 - Build the Background . . . . . . . . . . . . . . . .  12
  662.                Graphics and Highlighting . . . . . . . . . . . . . . . . . .  13
  663.                STEP 2 - Define Fields  . . . . . . . . . . . . . . . . . . .  13
  664.                Primary Edits . . . . . . . . . . . . . . . . . . . . . . . .  14
  665.                STEP 2a - Run the Screen Program  . . . . . . . . . . . . . .  16
  666.                STEP 3 - Define the Data Files  . . . . . . . . . . . . . . .  17
  667.                STEP 4 - Coding the Program   . . . . . . . . . . . . . . . .  18
  668.           Using the Editor . . . . . . . . . . . . . . . . . . . . . . . . .  19
  669.           PROC LOAD  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  20
  670.           PROC NAMEP . . . . . . . . . . . . . . . . . . . . . . . . . . . .  21
  671.           Event Driving  . . . . . . . . . . . . . . . . . . . . . . . . . .  22
  672.                The Linkage . . . . . . . . . . . . . . . . . . . . . . . . .  23
  673.                Adding the Linkage  . . . . . . . . . . . . . . . . . . . . .  23
  674.           Recording Data . . . . . . . . . . . . . . . . . . . . . . . . . .  23
  675.           Finding and Fixing Bugs  . . . . . . . . . . . . . . . . . . . . .  24
  676.           Hints, Tips & Techniques . . . . . . . . . . . . . . . . . . . . .  29
  677.           Sample Programs  . . . . . . . . . . . . . . . . . . . . . . . . .  29
  678.           Advanced Input Editing . . . . . . . . . . . . . . . . . . . . . .  31
  679.           Screen Handling  . . . . . . . . . . . . . . . . . . . . . . . . .  33
  680.                Screen Graphics . . . . . . . . . . . . . . . . . . . . . . .  33
  681.                Screen Offset . . . . . . . . . . . . . . . . . . . . . . . .  34
  682.           Structured Programming . . . . . . . . . . . . . . . . . . . . . .  36
  683.                Structured Constructs . . . . . . . . . . . . . . . . . . . .  36
  684.           Debugging  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  37
  685.           All About Registers  . . . . . . . . . . . . . . . . . . . . . . .  38
  686.           Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  40
  687.           Variables  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  43
  688.                Declaring Variables . . . . . . . . . . . . . . . . . . . . .  44
  689.                Dimensioned Variables . . . . . . . . . . . . . . . . . . . .  45
  690.           LANs and Multiuser . . . . . . . . . . . . . . . . . . . . . . . .  46
  691.                Commands  . . . . . . . . . . . . . . . . . . . . . . . . . .  46
  692.                Record Locking  . . . . . . . . . . . . . . . . . . . . . . .  46
  693.  
  694.  
  695.                                  Quic Reference Card
  696.                                        Page 12
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.                Record Unlocking  . . . . . . . . . . . . . . . . . . . . . .  47
  705.                File Locking  . . . . . . . . . . . . . . . . . . . . . . . .  47
  706.                Accession Number Management . . . . . . . . . . . . . . . . .  48
  707.           Restructuring an Indexed File  . . . . . . . . . . . . . . . . . .  49
  708.                Adding Keys . . . . . . . . . . . . . . . . . . . . . . . . .  49
  709.  
  710.      P R O G R A M M E R'S    R E F E R E N C E   M A N U A L  . . . . . . .  50
  711.                Naming Conventions  . . . . . . . . . . . . . . . . . . . . .  50
  712.                Format Files  . . . . . . . . . . . . . . . . . . . . . . . .  50
  713.                Building a Format . . . . . . . . . . . . . . . . . . . . . .  50
  714.                Build Screens . . . . . . . . . . . . . . . . . . . . . . . .  51
  715.           THE PROGRAMMING SYSTEM . . . . . . . . . . . . . . . . . . . . . .  55
  716.                Procedures  . . . . . . . . . . . . . . . . . . . . . . . . .  55
  717.                Screen Data Field Procedures  . . . . . . . . . . . . . . . .  55
  718.                Data Items  . . . . . . . . . . . . . . . . . . . . . . . . .  56
  719.           Standard Procedures  . . . . . . . . . . . . . . . . . . . . . . .  60
  720.                PROC BREAK  . . . . . . . . . . . . . . . . . . . . . . . . .  60
  721.                PROC ENTER  . . . . . . . . . . . . . . . . . . . . . . . . .  60
  722.                PROC ERROR  . . . . . . . . . . . . . . . . . . . . . . . . .  60
  723.                PROC KEY0-20  . . . . . . . . . . . . . . . . . . . . . . . .  61
  724.                PROC LOAD . . . . . . . . . . . . . . . . . . . . . . . . . .  61
  725.           Statement Types  . . . . . . . . . . . . . . . . . . . . . . . . .  61
  726.                Expressions . . . . . . . . . . . . . . . . . . . . . . . . .  63
  727.           Screen Offset  . . . . . . . . . . . . . . . . . . . . . . . . . .  63
  728.           Structured Programming . . . . . . . . . . . . . . . . . . . . . .  64
  729.           Tables and Table Handling  . . . . . . . . . . . . . . . . . . . .  65
  730.  
  731.      FILES AND FILE HANDLING . . . . . . . . . . . . . . . . . . . . . . . .  70
  732.                File Handler  . . . . . . . . . . . . . . . . . . . . . . . .  70
  733.                File System Interrupts  . . . . . . . . . . . . . . . . . . .  70
  734.                Loading BTSYS . . . . . . . . . . . . . . . . . . . . . . . .  70
  735.                File Types  . . . . . . . . . . . . . . . . . . . . . . . . .  71
  736.           Multi-key Indexed Sequential Files . . . . . . . . . . . . . . . .  71
  737.                File Keys . . . . . . . . . . . . . . . . . . . . . . . . . .  71
  738.                Reading and Writing . . . . . . . . . . . . . . . . . . . . .  71
  739.                Data File . . . . . . . . . . . . . . . . . . . . . . . . . .  72
  740.                Index File  . . . . . . . . . . . . . . . . . . . . . . . . .  72
  741.                Deleted Records . . . . . . . . . . . . . . . . . . . . . . .  73
  742.                File Maintenance  . . . . . . . . . . . . . . . . . . . . . .  73
  743.           Random Files . . . . . . . . . . . . . . . . . . . . . . . . . . .  73
  744.                Structure . . . . . . . . . . . . . . . . . . . . . . . . . .  73
  745.           Sequential (text) Files  . . . . . . . . . . . . . . . . . . . . .  73
  746.           SDF (Comma Delimited) Files  . . . . . . . . . . . . . . . . . . .  74
  747.           Indexed and Random File Handling . . . . . . . . . . . . . . . . .  74
  748.                Fundamentals  . . . . . . . . . . . . . . . . . . . . . . . .  74
  749.                Data Dictionary (FID) Files . . . . . . . . . . . . . . . . .  74
  750.                PC-DOS and MS-DOS File Considerations . . . . . . . . . . . .  75
  751.                File Restructuring  . . . . . . . . . . . . . . . . . . . . .  75
  752.           File Handling Commands . . . . . . . . . . . . . . . . . . . . . .  76
  753.  
  754.  
  755.                                  Quic Reference Card
  756.                                        Page 13
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.                MAKE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  76
  765.                OPEN  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  76
  766.                FILETYPE  . . . . . . . . . . . . . . . . . . . . . . . . . .  76
  767.                CLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . .  76
  768.                SECURE  . . . . . . . . . . . . . . . . . . . . . . . . . . .  76
  769.                PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  77
  770.                GET . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  77
  771.                KEY . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  77
  772.                POSN  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  77
  773.                READ  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  78
  774.                WRITE . . . . . . . . . . . . . . . . . . . . . . . . . . . .  78
  775.                FREE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  78
  776.                COPY  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  78
  777.  
  778.      ERROR HANDLING  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  80
  779.           Local Error Traps  . . . . . . . . . . . . . . . . . . . . . . . .  80
  780.           PROC ERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . .  81
  781.           ERRTRAP  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  82
  782.  
  783.      LANS and MULTIUSER SYSTEMS  . . . . . . . . . . . . . . . . . . . . . .  84
  784.                Principles  . . . . . . . . . . . . . . . . . . . . . . . . .  84
  785.           Multiuser Commands . . . . . . . . . . . . . . . . . . . . . . . .  84
  786.           MULTIUSER - ERRORS . . . . . . . . . . . . . . . . . . . . . . . .  87
  787.  
  788.      B I N A R Y   W O R S T A T I O N . . . . . . . . . . . . . . . . . . .  89
  789.           Starting Up  . . . . . . . . . . . . . . . . . . . . . . . . . . .  90
  790.           The Text Editor  . . . . . . . . . . . . . . . . . . . . . . . . .  93
  791.           Fid Generator  . . . . . . . . . . . . . . . . . . . . . . . . . . 104
  792.                FID Files . . . . . . . . . . . . . . . . . . . . . . . . . . 104
  793.                Referencing File Data Fields  . . . . . . . . . . . . . . . . 109
  794.  
  795.      Q - P R O 4   C O M M A N D S . . . . . . . . . . . . . . . . . . . . . 111
  796.           Symbology  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
  797.                Structure of the Commands . . . . . . . . . . . . . . . . . . 111
  798.                Naming Conventions  . . . . . . . . . . . . . . . . . . . . . 112
  799.                Data Items  . . . . . . . . . . . . . . . . . . . . . . . . . 112
  800.                Expressions . . . . . . . . . . . . . . . . . . . . . . . . . 114
  801.           Function Summary . . . . . . . . . . . . . . . . . . . . . . . . . 115
  802.           Command Summary  . . . . . . . . . . . . . . . . . . . . . . . . . 116
  803.           F u n c t i o n s  . . . . . . . . . . . . . . . . . . . . . . . . 119
  804.           C O M M A N D S  . . . . . . . . . . . . . . . . . . . . . . . . . 126
  805.  
  806.      Q - P R O 4  E R R O R   M E S S A G E S  . . . . . . . . . . . . . . . 233
  807.  
  808.      QMAINT  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
  809.  
  810.      Order Form  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
  811.  
  812.  
  813.  
  814.  
  815.  
  816.                                   License Agreement
  817.                                           0
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.                             THIS SOFTWARE IS NOT FOR SALE
  826.                             -----------------------------
  827.  
  828.      Q-PRO 4 Test Drive is subject to the following license terms and
  829.      conditions.
  830.  
  831.                              SINGLE COPY SOFTWARE LICENSE
  832.                                   QNE International
  833.                           ----------------------------------
  834.                           
  835.      THIS IS A SINGLE COPY SOFTWARE LICENSE granted by Quic-n-Easi Products,
  836.      Inc, trading as QNE International, a New Jersey Corporation with its
  837.      mailing address at 136 Granite Hill Court, Langhorne, PA 19047. Q-PRO 4
  838.      Test Drive is licensed to you as the end user.  It is not sold.
  839.  
  840.      Q-PRO 4 Test Drive is copyrighted material. You may use it on  a trial
  841.      basis provided you do not violate the copyright and if you  follow these
  842.      simple rules.  Use of Q-PRO 4 Test Drive on a regular basis requires
  843.      purchase as described later.
  844.  
  845.      You may not make any changes or modifications to Q-PRO Tests  DRIVE, and
  846.      you may not decompile, disassemble, or otherwise Reverse-engineer it. You
  847.      may not rent or lease it to others.
  848.  
  849.      You may make copies of Q-PRO 4 Test Drive only under the terms  of the
  850.      following section entitled "Limited License to Copy".
  851.  
  852.      This Software is Commercial Computer Software under Federal  Government
  853.      Acquisition Regulations and agency supplements to them. The Software is
  854.      provided to the Federal Government and its agencies  only under the
  855.      Restricted Bights Provisions of the Federal Acquisition Regulations
  856.      applicable to commercial computer software developed at private expense and
  857.      not in the public domain. The Use, Duplication, or disclosure by the Gov-
  858.      ernment is subject to restrictions as set forth in subdivision (c)(l)(ii)
  859.      of the Rights  in Technical Data and Computer Software clause at
  860.      252.227-7013.
  861.  
  862.      LIMITED WARRANTY.  QNE International does not warrant that the functions 
  863.      contained in the software will meet your requirements or that the  oper-
  864.      ation of the software will be uninterrupted or error free.  The warranty
  865.      does not cover any media or documentation which has been  subjected to
  866.      damage or abuse by you. The software warranty does not  cover any copy of
  867.      the software which has been altered or changed in any way by you or others. 
  868.      QNE International is not responsible for problems caused by changes in the
  869.      operating characteristics of the computer hardware or operating system
  870.      which are made after the delivery of the software.
  871.  
  872.      ANY IMPLIED WARRANTIES INCLUDING ANY WARRANTIES OF MERCHANTABILITY  OR
  873.      FITNESS FOR A PARTICULAR PURPOSE ARE LIMITED TO THE TERM OF THE
  874.      EXPRESS WARRANTIES. Some States do not allow limitations on how long an
  875.  
  876.  
  877.                                   License Agreement
  878.                                           1
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  
  885.  
  886.      implied warranty lasts, so the above limitation may not apply to you.
  887.  
  888.      QNE International SHALL NOT IN ANY CASE BE LIABLE FOR SPECIAL, INCIDENTAL,
  889.      CONSEQUENTIAL,INDIRECT OR OTHER SIMILAR DAMAGES ARISING FROM ANY BREACH OF
  890.      THESE WARRANTIES EVEN IF QNE International OR ITS AGENT HAS BEEN ADVISED OF
  891.      THE POSSIBILITY OF SUCH DAMAGES.  Some states do not allow the exclusion or
  892.      limitation of incidental or consequential  damages, so the above limitation
  893.      or exclusion may not apply to you.
  894.  
  895.      The warranties set forth above are in lieu of all other express end 
  896.      implied warranties, whether oral, written, or implied, and the remedies set
  897.      forth above are your sole and exclusive remedy.
  898.  
  899.      LIMITATION OF LIABILITY. In no case shall QNE International's liability
  900.      exceed the license fees paid for the right to use Q-PRO 4 TEST DRIVE or ten
  901.      Dollars ($10.00), whichever is greater.
  902.  
  903.      INTEGRATION. This License constitutes the entire agreement and   
  904.      understandIng between the parties and supersedes any prior agreement or
  905.      understanding whether oral or written, relating to the  subject of this
  906.      License. This Agreement may only be modified by a  written agreement signed
  907.      by QNE International.
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.                                   License Agreement
  939.                                           2
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.                                LIMITED LICENSE TO COPY
  948.                                =======================
  949.  
  950.      You are granted a limited license to copy Q-PRO 4 Test Drive only for the
  951.      trial use of others subject to the software license described above, and
  952.      also the following:
  953.  
  954.      Q-PRO 4 Test Drive must be copied in unmodified form, complete with the
  955.      following files:
  956.  
  957.      QNE.EXE   The Q-PRO 4 TEST DRIVE program
  958.  
  959.      BW.EXE    The Binary Workstation Editor
  960.  
  961.      BWFID.EXE The Binary Workstation FID generator
  962.  
  963.      QNE.DOC   The Q-PRO 4 Documentation on disk.
  964.  
  965.  
  966.      The full and unmodified Q-PRO 4 Test Drive documentation must be included
  967.      with the copy.
  968.  
  969.      No fee, charge or other compensation may be accepted or requested by anyone
  970.      without express written permission from QNE International.
  971.  
  972.      Q-PRO 4 Test Drive may not be distributed in conjunction with any other
  973.      product or service without a specific license to do so from QNE
  974.      International.
  975.  
  976.      Q-PRO 4 Test Drive may be distributed only in North America - DISTRIBUTION
  977.      OF Q-PRO 4 Test Drive OUTSIDE OF NORTH AMERICA IS STRICTLY FORBIDDEN.
  978.  
  979.      Operators of electronic bulletin board systems (Sysops) may post Q-PRO 4
  980.      Test Drive for downloading by their users without written permission only
  981.      as long as the above conditions are met.  A fee may be charged for access
  982.      to the BBS as long as no specific fee is charged for access to the Q-PRO 4
  983.      Test Drive files.
  984.  
  985.      Distributors of public domain and user supported software, such as disk
  986.      vending services, may distribute copies of Q-PRO 4 Test Drive subject to
  987.      the above conditions only after obtaining written permission from QNE
  988.      International.  Such permission usually is granted; please write for
  989.      details.
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.                                   License Agreement
  1000.                                           3
  1001.  
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.  
  1008.                  I N T R O D U C I N G   Q-PRO 4  T E S T   D R I V E
  1009.                  ====================================================
  1010.  
  1011.      Q-PRO 4 Test Drive is the "try before you buy" version of Q-PRO 4.  QNE
  1012.      International created it to allow you to "test drive" Q-PRO 4 before
  1013.      committing your hard earned dollars.  This has benefits for both the users
  1014.      and the authors.
  1015.  
  1016.      First of all, though, you must be aware that Q-PRO 4 and Q-PRO 4 Test Drive
  1017.      ARE NOT free software, NOR are they in the PUBLIC DOMAIN.  Both programs
  1018.      are fully copyrighted works protected to the full extent of US and
  1019.      international copyright law.
  1020.  
  1021.      Why allow a program "test drive"?  Q-PRO 4 Test Drive is based on a
  1022.      marketing technique called "shareware" or "user-supported software",  which
  1023.      is a means for the computing community to receive quality software  while
  1024.      directly supporting authors.  It is based on the idea that the  value and
  1025.      utility of software is often best assessed by the user on his or her own
  1026.      system.  Only after using a program can one really determine  whether it
  1027.      serves personal applications, needs and tastes.
  1028.  
  1029.      The benefits to users are fairly obvious: you are allowed to thoroughly
  1030.      evaluate the software before purchasing it.  How many times have you
  1031.      purchased an expensive piece of software only to find that it doesn't do
  1032.      what you need?
  1033.  
  1034.      Software authors benefit by creating a distribution channel of satisfied
  1035.      users who 
  1036.  
  1037.      recommend and pass along their product.  This"pyramid" effect can be a very
  1038.      effective marketing technique, and is vastly less expensive than
  1039.      traditional marketing techniques.  This is not to say that "test drives"
  1040.      and more traditional methods like magazine advertising are mutually
  1041.      exclusive.  They may be used together very effectively to target different
  1042.      segments of the market.
  1043.  
  1044.      What does this mean to you?  While you are granted a limited license to
  1045.      evaluate the program on a trial basis, regular use of the program requires
  1046.      purchase.  What is a "trial basis"?  Kicking the program around over a
  1047.      weekend to see how it works is certainly using it on a trial basis. 
  1048.      Installing and using the program in a production test environment for two
  1049.      weeks is trial use.  Using the software twice a week for regular work for
  1050.      three months is not and therefore requires purchase.  Using the program
  1051.      regularly for any regular task, especially if it has replaced other
  1052.      software, is not trial use.  These examples are not intended as definitive
  1053.      rules, but more as general guidelines.
  1054.  
  1055.      You are not allowed to modify the software under any conditions.  We do,
  1056.      however, encourage you to create "add-on" support utilities and program to
  1057.      enhance your and others' enjoyment of the program.
  1058.  
  1059.  
  1060.                                      Introduction
  1061.                                           4
  1062.  
  1063.  
  1064.  
  1065.  
  1066.  
  1067.  
  1068.  
  1069.      You may copy the program for the trial use of others subject to the rule
  1070.      outlined in the previous section "Limited License to Copy".  In general,
  1071.      you may only copy the program in complete and unmodified form, as we
  1072.      distribute it.
  1073.  
  1074.      You may not charge any fee for copies of the program without written
  1075.      permission from QNE International.  This applies especially to disk
  1076.      vendors.   Some services mislead customers into thinking they have
  1077.      purchased the software, rather than just the disk and duplication service. 
  1078.      If you have purchased this product from a disk vendor and feel they were
  1079.      misleading about what you have purchased, please write us and we will
  1080.      investigate the matter.
  1081.  
  1082.      You may not include Q-PRO 4 Test Drive with any other product,   whether
  1083.      hardware or software, without specific license.  For example, you   may not
  1084.      include Q-PRO 4 Test Drive on the hard drives of computers   you  sell, or
  1085.      include it with copies of software you have developed.
  1086.  
  1087.  
  1088.                                   Purchasing Q-PRO 4
  1089.                                   ==================
  1090.  
  1091.      After using Q-PRO 4 Test Drive for a while, you need to decide if you want
  1092.      to continue using it on a regular basis.  If not, please feel free to
  1093.      continue copying it for the trial use of others, or to pass your copy along
  1094.      to a friend.
  1095.  
  1096.      Please note that there are two versions of the software, Q-PRO 4 and Q-PRO
  1097.      4 Test Drive.  The TEST DRIVE version may be copied and used for evaluation
  1098.      as described above.  The purchased version of Q-PRO 4, however, may only be
  1099.      copied for backup purposes.  After receiving your purchased copy of Q-PRO 4
  1100.      you may continue to copy Q-PRO 4 Test Drive for friends; you may not copy
  1101.      Q-PRO 4.
  1102.  
  1103.      Why should you purchase Q-PRO 4?  To pay for the software which you are
  1104.      gainfully using, and to support its authors and encourage them to produce
  1105.      more high quality software.  And because regular use of Q-PRO 4 Test Drive
  1106.      without purchase is a violation of the license
  1107.      under which you use it.
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.                                      Introduction
  1122.                                           5
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130.      When you purchase Q-PRO 4 for $50.00, you will receive the following:
  1131.  
  1132.       -   Perpetual license for you to use the software you have purchased. 
  1133.       -   A two disk program set including a serialized Q-PRO 4.
  1134.       -   A 300+ page professionally typeset and printed manual which includes a
  1135.           tutorial and index.
  1136.       -   30 days (up to 2 hours) telephone technical support.
  1137.  
  1138.      When you purchase Q-PRO 4 Plus for $90.00, you will receive, in addition to
  1139.      the above:
  1140.  
  1141.       -   Utilities to import/export Lotus files, to import dBASE II/III/IV data
  1142.           files, to custom configure your Q-PRO 4 keyboard any way you want, and
  1143.           to custom configure Binary WorkStation.
  1144.       -   The Q-PRO 4 non-procedural report generator.
  1145.       -   60 days (up to 3 hours) of telephone technical support.
  1146.        
  1147.      To order via credit card, call our business office at (800) 333-0448. Cash
  1148.      and check purchasers should use the order form in the back of this manual.
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.  
  1159.  
  1160.  
  1161.  
  1162.  
  1163.  
  1164.  
  1165.  
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.                                      Introduction
  1183.                                           6
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.                                Q-PRO 4  O V E R V I E W
  1192.                               ======================== 
  1193.      Design Freedom
  1194.      --------------
  1195.      Q-PRO 4's design philosophy of Q-PRO 4 is different from almost any other
  1196.      language or "database manager" that you have ever seen.  Our approach makes
  1197.      the language work for you, not vice versa.
  1198.  
  1199.      Non Sequitur
  1200.      ------------
  1201.      All of you have used and been used by BASIC, FORTRAN, or, more likely,
  1202.      dBASE II or dBASE III (or IV - which is probably why you are reading these
  1203.      words!).  All are sequential languages.
  1204.  
  1205.      In sequential languages, the program code is running continuously.  If
  1206.      there is to be interaction with the operator through the keyboard/CRT, the
  1207.      programmer must handle this interaction in excruciating detail under
  1208.      program control.  These languages were either designed before the advent of
  1209.      CRT's or the authors forgot that in a modern environment, the user of an
  1210.      application is almost continuously communicating with the application
  1211.      through the keyboard.
  1212.  
  1213.      To overcome this design shortcoming, the programmer must write enormous
  1214.      amounts of code to communicate with the user.  More than likely, because of
  1215.      the ever-present deadlines, the 
  1216.  
  1217.      screen becomes a repetitive question and answer session--a completely
  1218.      unsatisfactory human interface.
  1219.  
  1220.      Events Drive Us
  1221.      ---------------
  1222.      How is Q-PRO 4 different?  Q-PRO 4 is an "event" driven language not a
  1223.      "sequential" language.  An event driven language itself detects keystrokes
  1224.      or the status of a screen input field as an event automatically.  This
  1225.      information is immediately available for program control.  The programmer
  1226.      then determines if and where in the program to transfer control.  Now you
  1227.      can concentrate on the application, not the management of the environment.
  1228.  
  1229.      Q-PRO 4 senses events at several levels.  The most fundamental is automatic
  1230.      sensing of a keystroke which is numeric when it should have been alpha,
  1231.      etc.  At the next level, it may sense a screen field that must be filled
  1232.      when it has not been.  At the next level, at the programmers option, Q-PRO
  1233.      4 branches to a segment of the program code.
  1234.  
  1235.      It's Magic
  1236.      ----------
  1237.      How is this magic done?  The Q-PRO 4 entry screen is a set of
  1238.      fill-in-the-blanks fields which, at the option of the programmer, may or
  1239.      may not be enterable by the operator.  Normally, the screen is set up as a
  1240.  
  1241.  
  1242.                                        Overview
  1243.                                           7
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.      true fill-in-the-blanks type which closely resembles the form the user is
  1252.      accustomed to.  The programmer completes a short form on the screen which
  1253.      defines the field.  This definition sets the attributes of the field; such
  1254.      as its name, length, alpha only, numeric only, justification, may enter,
  1255.      must enter, etc.
  1256.  
  1257.      If the operator types a numeric in an alpha only field, Q-PRO 4 detects it,
  1258.      halts entry and displays an error message.  The keyboard is disabled except
  1259.      for the ESCAPE key.  The bad character will not be displayed.  Pressing the
  1260.      ESCAPE key will turn control back to the operator.  In this manner, Q-PRO 4
  1261.      forces correct entry according to field definition without program
  1262.      intervention.
  1263.  
  1264.      The operator moves from entry field to entry field on the screen either by
  1265.      filling up the field or by pressing the RETURN key.  The RETURN key itself
  1266.      may be detected as an event.  If the field is properly entered, and a
  1267.      program segment is specified for the field, the program segment, called a
  1268.      procedure, will be executed.  
  1269.      Now the application is entirely under the control of the programmer.  The
  1270.      programmer may use any of the over 100 Q-PRO 4 commands to error check the
  1271.      field, search for and display a record from a file or any other tricky
  1272.      stuff that programmers are so fond of.
  1273.  
  1274.      Programmable Function Keys
  1275.      --------------------------
  1276.      This same capability allows Q-PRO 4 to detect 21 function keys, the enter
  1277.      key and other editing keys.  The programmer can do whatever his heart
  1278.      desires when one of these keys is pressed by the operator.  For example,
  1279.      F10 could terminate the application, F9 could display a help screen, etc.
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.                                        Overview
  1303.                                           8
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.      Another benefit of this approach is that, by use of screen field names or
  1312.      by symbolic notation, the screen fields may be examined for consistency. 
  1313.      And, calculations may be performed on the screen.
  1314.  
  1315.      Modern Commands
  1316.      ---------------
  1317.      All Q-PRO 4's commands are English-like and logically consistent in
  1318.      structure.  They always start with a verb, and are followed by an operand
  1319.      and optionally by a modifier.  Extended commands will have additional
  1320.      operands and additional modifiers.
  1321.  
  1322.      Databases Are Poor Relations
  1323.      ----------------------------
  1324.      Many so-called databases are entirely relational.  Q-PRO 4 applications may
  1325.      be set up relationally, hierarchically, or any other strange way that suits
  1326.      the programmer and the application.  We do not presume to know how your
  1327.      databases should be set up, but we do know that not all databases in an
  1328.      application are related!  For example, in a typical order entry
  1329.      application, the product database is rarely related to the sales person
  1330.      database.  
  1331.  
  1332.      They may or may not be related on a transaction.  The point is, of course,
  1333.      that you, the applications designer, are the only one who knows how the
  1334.      various databases work together.  Q-PRO 4's function is to give you the
  1335.      freedom to do it your way quickly and with the least possible systems and
  1336.      programming overhead.
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.  
  1343.  
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  
  1361.  
  1362.                                        Overview
  1363.                                           9
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.                             Q - P R O 4   T U T O R I A L
  1372.                             =============================
  1373.  
  1374.      Q-PRO 4 Fundamentals
  1375.      --------------------
  1376.      Q-PRO 4 has three segments, the screens, the File Items Descriptor (or FID)
  1377.      and the program code.  The Binary WorkStation editor is used to create the
  1378.      entire application.  Actually, Binary WorkStation has three editors: one
  1379.      for program code, one for screens, and one for FIDs.
  1380.  
  1381.      Program Code
  1382.      ------------
  1383.      The program code is broken into segments called procedures or PROCs.  The
  1384.      program code editor of Binary WorkStation has the normal text editor
  1385.      capabilities you would expect of any text editor.  In addition, it has
  1386.      special features specifically for Q-PRO 4 programming.  Some of these
  1387.      features include:  a syntax checker, a macro code generator, and a file
  1388.      items descriptor (FID) generator.  Binary WorkStation is also a very good
  1389.      editor for text files.  
  1390.  
  1391.      When Binary WorkStation is first loaded the program code editor is
  1392.      executed.
  1393.  
  1394.      Screens 
  1395.      --------
  1396.      Screens are created in a what-you-see-is-what-you-get (WYSIWYG) mode with
  1397.      the screen editor portion of Binary WorkStation.
  1398.  
  1399.      You "paint" the background for the screen window.  This is the labels or
  1400.      operator prompts, colors and line graphics.  The labels are created by
  1401.      positioning the cursor where you want them and typing the text.  The lines
  1402.      are drawn by changing to the graphics mode.  Then they are drawn with the
  1403.      cursor left and right keys.  The intersections are placed with the function
  1404.      keys.  
  1405.         
  1406.      You define a data entry area or screen data field by pressing a function
  1407.      key to display the screen data field of the screen editor.  On this screen
  1408.      you specify the characteristics of the field and its primary edits such as
  1409.      width, type (alpha, numeric,etc.), may enter, must enter, may tab, must
  1410.      tab, etc.  
  1411.  
  1412.      As you will see, creating a dramatic, attractive screen for the user is a
  1413.      sheer delight.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.                                        Tutorial
  1423.                                           10
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.                                  Installing Q-PRO 4 
  1432.                                   ==================
  1433.  
  1434.      If you have not already done so, it is time to unpack and install Q-PRO 4. 
  1435.      Simply unarc the Q-PRO4.ARC file in the directory you are going to work in.
  1436.  
  1437.      Binary WorkStation has extensive help screens.  You can refer to them from
  1438.      any subdirectory where you happen to be if you use the DOS variable BWHLP. 
  1439.      Use this format in autoexec.bat: set bwhlp=<d>:<sub> (where <d> = drive and
  1440.      <sub> = subdirectory where Binary WorkStation is).
  1441.       
  1442.      Check for READ.ME
  1443.      -----------------
  1444.      The latest information about Binary WorkStation is on the Binary
  1445.      WorkStation diskette.  It is a plain ASCII file.  Please take a look at it.
  1446.  
  1447.  
  1448.  
  1449.                                    Example Program
  1450.                                    ===============
  1451.  
  1452.      About This Chapter 
  1453.      ------------------
  1454.      In this chapter, we will develop a small Q-PRO 4 application.  Although
  1455.      this application is simple, it is illustrative of the techniques used in
  1456.      many applications.  Additional material on technique is in the Hints, Tips
  1457.      & Techniques chapter and in the sample programs.
  1458.  
  1459.  
  1460.      Steps in Building a Q-PRO 4 Program
  1461.      -----------------------------------
  1462.  
  1463.           Step
  1464.       
  1465.           1.  Build the background
  1466.           2.  Define the data entry fields
  1467.           3.  Define the data files
  1468.           4.  Code the program
  1469.           5.  Run the program
  1470.  
  1471.      Usually we will take the steps in order, but there will be variations for
  1472.      clarity and flow.   
  1473.  
  1474.      Load Binary WorkStation
  1475.      ----------------------- 
  1476.      Change directory to the directory that Q-PRO 4 is on.  Load Binary
  1477.      WorkStation and tell it the program file you will be using by typing BW
  1478.      CUST.QNE (Note the space between BW and CUST.QNE) and then press RETURN. 
  1479.      The options screen will display.  Press RETURN.  You will be in the program
  1480.  
  1481.  
  1482.                                        Tutorial
  1483.                                           11
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.      code editor portion of Binary WorkStation.  This is a blank screen that we
  1492.      will use later to write the procedural program code portion of the program.
  1493.  
  1494.      /------------------------------\
  1495.      |STEP 1 - Build the Background |
  1496.      \------------------------------/
  1497.  
  1498.      Press F8 to invoke the screen editor and display the screen.  A blank
  1499.      screen will display.  Visualize the screen as a clean page to draw your
  1500.      form on.
  1501.  
  1502.           About Backgrounds
  1503.           -----------------
  1504.           The background is our term for the constant material on the screen. 
  1505.           This material is variously referred to as "prompts", "labels",
  1506.           "operator information", . . .
  1507.  
  1508.           In Q-PRO 4, the background most often emulates the pre-printed portion
  1509.           of a printed form.  
  1510.  
  1511.      Move the cursor on the screen using your system cursor control keys and
  1512.      type the text until your screen looks like the one following.  Remember,
  1513.      with Binary WorkStation, you have insert character and line, delete
  1514.      character and line, etc.  The composition of the screen is "free-form" so
  1515.      feel free to arrange it for the best effect on your screen.  Leave some
  1516.      room in the bottom third of the screen for additions to be made later.  
  1517.  
  1518.      You should generally follow this layout:
  1519.  
  1520.      /-------------------------------------------------------------------------\
  1521.      |                                                                         |
  1522.      |                                                                         |
  1523.      |                        ENTER NEW CUSTOMERS                              |
  1524.      |                                                                         |
  1525.      |                                                                         |
  1526.      |      Name:                                                              |
  1527.      |                                                                         |
  1528.      |      Street and Number:                                                 | 
  1529.      |                                                                         |
  1530.      |      City:                                 State:    ZIP:               |
  1531.      |                                                                         | 
  1532.      |                                                                         |
  1533.      |                                                                         |
  1534.      |                                                                         |
  1535.      |                                                                         |
  1536.      |                                                                         |
  1537.      |                                                                         |
  1538.      |                        ESC - To Exit to System                          |
  1539.      |                                                                         |
  1540.  
  1541.  
  1542.                                        Tutorial
  1543.                                           12
  1544.  
  1545.  
  1546.  
  1547.  
  1548.  
  1549.  
  1550.  
  1551.      |                                                                         |
  1552.      \-------------------------------------------------------------------------/
  1553.  
  1554.  
  1555.                               Graphics and Highlighting
  1556.                               =========================
  1557.  
  1558.      You can enhance the readability and make a more dramatic presentation on
  1559.      the screen by using line graphics and highlighting.  Highlighting and
  1560.      business graphics depend on the computer or terminal you are using.  Not
  1561.      all support these features.
  1562.  
  1563.      Business Graphics
  1564.      -----------------
  1565.      To put business graphics on the window: 
  1566.  
  1567.           1.   Press FUNCT 0 (Funct 10 on the IBM-PC) to put Binary WorkStation
  1568.                in the graphics mode.
  1569.           2.   Use the cursor controls to draw horizontal and vertical lines and
  1570.                the function keys to print the corners and intersections.  See
  1571.                the Binary WorkStation section for more details.
  1572.  
  1573.      Highlighting
  1574.      ------------
  1575.      Highlighting takes one character position on the screen.  You must make
  1576.      allowance for this when you use highlighting.  To highlight:
  1577.  
  1578.           1.   Place the cursor to the left of the background field that you
  1579.                want to highlight and press F3, the highlight on key.
  1580.  
  1581.  
  1582.           2.   Move the cursor to the right of the field to be highlighted. 
  1583.                Press the highlight off key, F4.
  1584.  
  1585.      The text between the highlight on character and the highlight off character
  1586.      will be highlighted.  On some machines, such as the IBM-PC, the machine
  1587.      will not know that the highlight exists until you go back to the menu by
  1588.      pressing ESCAPE and then re-display the screen by pressing menu F8.
  1589.  
  1590.  
  1591.      /------------------------------\
  1592.      |STEP 2 - Define Fields        |
  1593.      \------------------------------/
  1594.  
  1595.  
  1596.      Q-PRO 4 Data Entry Fields
  1597.      -------------------------
  1598.      One of Q-PRO 4's strongest features is its use of data entry fields. 
  1599.      Overall, they emulate the blanks to be filled in on a preprinted form.
  1600.  
  1601.  
  1602.                                        Tutorial
  1603.                                           13
  1604.  
  1605.  
  1606.  
  1607.  
  1608.  
  1609.  
  1610.  
  1611.  
  1612.  
  1613.      To Enter or Not
  1614.      ---------------
  1615.      As you will see, defining them is simplicity itself; there is no coding and
  1616.      the fields are easily moveable.  Screen data fields may or may not be
  1617.      enterable by the operator.  Or, they may be created enterable and then made
  1618.      nonenterable!
  1619.  
  1620.      Primary Edits
  1621.      -------------
  1622.      At the time the fields are defined, primary edits are also defined: 
  1623.      alpha/numeric only, may enter, must enter, must fill, etc.  Again, there is
  1624.      no program code and the primary edits may be changed at any time.
  1625.       
  1626.      Field Definition
  1627.      ----------------
  1628.      Move the cursor to the right of the colon(:) following CUSTOMER NUMBER. 
  1629.      Press F1.  The form below will be displayed.  As you see, it is arranged in
  1630.      columns.  You define the field by describing it in each column.  Here is
  1631.      how you do it: 
  1632.  
  1633.      Column      Your Entry             Meaning
  1634.      ------      ----------   ------------------------------------------------- 
  1635.      Field name     NAME      From now on, Q-PRO 4 will use the identifier NAME
  1636.                               to refer to the contents of this screen data
  1637.                               field.  In other words, NAME is now a variable in
  1638.                               your program.  See the Naming Conventions Section
  1639.                               in the Q-PRO 4 Reference Manual for a full explan-
  1640.                               ation of naming conventions.  Press the TAB key.
  1641.  
  1642.      Len.           30        This specifies that up to thirty characters will
  1643.                               be allowed in the NAME screen data field.  As we
  1644.                               progress, you will see how the screen data field
  1645.                               definition will narrow the operator's choices.
  1646.                               Press the TAB key twice to skip to Type. 
  1647.      Row            <tab>     This is the row coordinate.  It is already filled
  1648.                               in for you.  Pressing tab skips over it.
  1649.  
  1650.      Col            <tab>     The column coordinate is filled in for you.
  1651.  
  1652.      Type           <tab>     The Type descriptor is a two character field.  The
  1653.                               first character forces the operator to put in the
  1654.                               correct type of data.  As we will allow anything
  1655.                               here just press TAB. Refer to the Quick Reference
  1656.                               Card for the meaning of all the field descriptor
  1657.                               codes.  The second character may be blank, equal
  1658.                               sign (=) for autoduplication, or question mark (?)
  1659.                               for an invisible field
  1660.  
  1661.  
  1662.                                        Tutorial
  1663.                                           14
  1664.  
  1665.  
  1666.  
  1667.  
  1668.  
  1669.  
  1670.  
  1671.  
  1672.  
  1673.      Just           L         This field specifies the justification.  The L
  1674.                               will cause data entered in the screen data field
  1675.                               to be left justified.
  1676.  
  1677.      Fill Char      <tab>     Frequently numeric fields are right justified and
  1678.                               use a zero (0) as a leading character.  You may
  1679.                               specify any leading character.  Do not use a
  1680.                               number sign (#) until you read about it in the
  1681.                               Programmer's Reference Manual.
  1682.  
  1683.  
  1684.      May Ent.       Y         Since we are going to allow entry, put a "Y" here.
  1685.  
  1686.  
  1687.      Must Ent.      Y         We want to force the user to put something here.
  1688.  
  1689.      Must Fill      N         The user does not have to completely fill the
  1690.                               field.
  1691.  
  1692.      Must Tab       N         We are not going to require the user to press tab
  1693.                               to leave the field. 
  1694.  
  1695.      Procedure
  1696.       Name          <tab>     At the moment we are not going to write a
  1697.                               procedure for this field.
  1698.  
  1699.                * * * You are now finished defining the field NAME * * * 
  1700.  
  1701.      Press ENTER to return to the background screen.  The previously typed
  1702.      screen is displayed again.  The NAME screen data entry field looks like
  1703.      this:
  1704.  
  1705.  
  1706.      NAME :   ################
  1707.  
  1708.      The number signs (###) indicate the presence of a defined screen data field
  1709.      and its length.  We will refer to these defined fields as screen data
  1710.      fields.
  1711.  
  1712.      Use the same procedure for all the other fields on the screen using the
  1713.      field specifications below.
  1714.  
  1715.      Screen  Field                            Fill  May Must Must Must Proceed
  1716.      Label   Name      Len  Row Col Type Just Char. Ent Ent  Fill  Tab   Name
  1717.      ------ |----------------------------------------------------------------
  1718.      NAME   |  NAME    30                 L          Y    N    N     N
  1719.      STREET |  STREET  30                 L          N    N    N     N
  1720.  
  1721.  
  1722.                                        Tutorial
  1723.                                           15
  1724.  
  1725.  
  1726.  
  1727.  
  1728.  
  1729.  
  1730.  
  1731.      CITY   |  CITY    20                 L          N    N    N     N
  1732.      STATE  |  STATE    2             A   L          Y    N    Y     N
  1733.      ZIP    |  ZIP      5             D   L          Y    Y    Y     Y
  1734.                                                          
  1735.  
  1736.      Note:  when a field format definition for every field has been entered,
  1737.      this segment of the program is complete.  Press F8 to return to the coding
  1738.      section.
  1739.  
  1740.      Press Control and U at the same time.  This dialog screen will display:
  1741.  
  1742.      /-------------------------------------------------------------------\
  1743.      |                                                                   |
  1744.      |  Save this file? [Y]         Save in Q-PRO 4 format? [Y]          |
  1745.      |                                                                   |
  1746.      |  File name [CUST.QNE                                  ]           |
  1747.      \-------------------------------------------------------------------/
  1748.  
  1749.      * * *  MAKE SURE THAT the first two questions are answered - Y. ****
  1750.  
  1751.      Press enter.   
  1752.  
  1753.  
  1754.      /---------------------------------\
  1755.      | STEP 2a - Run the Screen Program |
  1756.      \---------------------------------/
  1757.  
  1758.      1.   Press ENTER.  Press F8.  You will be moved to the program code editor.
  1759.  
  1760.      2.   Hold the CTRL key down and press U.  Press ENTER when the dialog
  1761.           screen displays.
  1762.      3.   Hold the CTRL key down and press Q.  When the dialog screen is
  1763.           displayed, press RETURN to run your program.  It will be loaded by the
  1764.           runtime interpreter (QNE.EXE), and execution will begin.  The data
  1765.           entry screen that you have built will be displayed ready for data
  1766.           entry.
  1767.  
  1768.      Entering Data
  1769.      -------------
  1770.      Begin typing data using the CURSOR RIGHT key or the ENTER key to go forward
  1771.      from data entry field to data entry field.  Use the SHIFT TAB key or the
  1772.      CURSOR LEFT key to go backwards from field to field.  If the data you key
  1773.      does not agree with the field specification, then an error message will be
  1774.      displayed.  To resume keying, press ESC.
  1775.  
  1776.      Changing Data
  1777.      -------------
  1778.      To change the data in a field, press the ENTER key to go forward or the
  1779.      Shift TAB key to go backward until you get to the correct field.  Either
  1780.  
  1781.  
  1782.                                        Tutorial
  1783.                                           16
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.  
  1790.  
  1791.      type over the previous data, or use the CLEAR TO END OF LINE (CONTROL END)
  1792.      key to erase the rest of the data in that field.  You may also use the
  1793.      INSERT/DELETE character keys.  Then type the correct data.
  1794.  
  1795.      Once you have entered all the data for a customer, press END.  The screen
  1796.      will clear for additional entries.
  1797.  
  1798.      When you have finished, press ESC to return to Binary WorkStation.
  1799.       
  1800.  
  1801.      ***  NOTE:  no data that has been typed on the screen will actually be 
  1802.           written on a data file because the data files and data file
  1803.           handling have not yet been programmed.
  1804.  
  1805.  
  1806.      /-----------------------------------\
  1807.      |  STEP 3 - Define the Data Files   |
  1808.      \-----------------------------------/
  1809.  
  1810.      FID Generator
  1811.      -------------
  1812.      The data in a data file is arranged into fields which have names.  The File
  1813.      Item Description Generator, is used to create the file, called a FID file,
  1814.      which contains the names of the fields in the data file.  The FID file is
  1815.      also used for creating and opening data files.  FID is a menu selection
  1816.      from Binary WorkStation.
  1817.  
  1818.      Select the FID generator by holding down the CNTL key and pressing V.  At
  1819.      the bottom of the screen, this line will display:
  1820.  
  1821.      FID Name or Number [                                   ]
  1822.  
  1823.      In the blank provided for FID Name or Number, type CUST.FID.  The FID
  1824.      definition screen will display.
  1825.  
  1826.      Current File [CUST.FID                            ]
  1827.        
  1828.        Item name    Len.  Type     Description                  Reps
  1829.      [           ] [   ]   [ ]   [                            ] [  ]
  1830.      [           ] [   ]   [ ]   [                            ] [  ]
  1831.      [           ] [   ]   [ ]   [                            ] [  ]
  1832.      [           ] [   ]   [ ]   [                            ] [  ]
  1833.           .
  1834.           .
  1835.           .
  1836.           .
  1837.      [           ] [   ]   [ ]   [                            ] [  ]
  1838.      [           ] [   ]   [ ]   [                            ] [  ]
  1839.      [           ] [   ]   [ ]   [                            ] [  ]
  1840.  
  1841.  
  1842.                                        Tutorial
  1843.                                           17
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.      [           ] [   ]   [ ]   [                            ] [  ]
  1852.  
  1853.  
  1854.      Creating the FID File
  1855.      ---------------------
  1856.      We will create a FID file using Quic FID.  This feature lets you create the
  1857.      FID to match the screen with no tedious typing.  We are assuming that the
  1858.      name of the application file you used in the previous sections was
  1859.      CUST.QNE.  
  1860.  
  1861.      Follow these steps:
  1862.      -------------------
  1863.       
  1864.      1.  Hold down the shift key and press F2.
  1865.      2   Enter the name of our format file: (CUST.QNE)
  1866.      3.  Press F4 (Update FID file) to save the FID file on disk. 
  1867.      4.  Press SHIFT F10 (Go to Binary WorkStation program code editor).
  1868.  
  1869.      Indexed or Random
  1870.      -----------------
  1871.      The FID determines what type of file will be created when it is used by
  1872.      Q-PRO 4 to create a file.  If the FID is defined with a key (or keys), the
  1873.      data file will be indexed.  If no keys, the data file will be random.
  1874.  
  1875.      Keys in Indexed Data Files
  1876.      --------------------------
  1877.      The key is another term for the sequence of the indexed data file.  In the
  1878.      customer file, the name of the customer is the key.  When you enter
  1879.      customers, no matter what sequence that you enter them, the logical order
  1880.      will be alphabetic by customer.  For a more detailed discussion, see the
  1881.      section on FIDS in the FID Generator section of the Binary WorkStation
  1882.      Reference Chapter.
  1883.  
  1884.      /-----------------------------\
  1885.      | STEP 4 - Coding the Program |
  1886.      \-----------------------------/
  1887.  
  1888.                                   Language Structure
  1889.                                   ==================
  1890.      Event Driving
  1891.      -------------
  1892.      In a previous section we pointed out that Q-PRO 4 is event driven.  An
  1893.      event may be the operator pressing TAB to leave a screen data field or
  1894.      pressing a function key.  The application designer decides if this event
  1895.      will cause transfer to the command section of the program file.  The
  1896.      command section consists of procedures.
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.                                        Tutorial
  1903.                                           18
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.      Procedures
  1912.      ----------
  1913.      The procedure, or PROC, is a series of Q-PRO 4 commands.  It may be
  1914.      specific to a screen data field or function key or more global like a
  1915.      subroutine.  When control is transferred to it, the procedure executes its
  1916.      commands and, at the application designer's option, returns control to the
  1917.      screen.  Thus, the application designer always has control.  Procedures
  1918.      have names to identify them.
  1919.       
  1920.      Linkage
  1921.      -------
  1922.      The PROCs are linked to the screen data field by the entry on the screen
  1923.      data field definition line for Proc Name (field procedure name), wherein a
  1924.      PROC name is entered.  When the operator has gotten over the primary
  1925.      hurdles, MUST ENTER, MUST FILL, etc. and presses TAB, the PROC named in
  1926.      Proc Name will be executed.  This is how Q-PRO 4 knows what procedure to
  1927.      execute for this event or the linkage from the keyboard/screen to the
  1928.      commands.
  1929.  
  1930.  
  1931.                                    Using the Editor
  1932.                                    ----------------
  1933.  
  1934.      Overview
  1935.      --------
  1936.      Binary WorkStation is a complete text editor.  Like most text editors, it
  1937.      has full facilities for entering, deleting, modifying and moving text.
  1938.  
  1939.      In general, all you need do is type in the code.  The following is a
  1940.      thumbnail description of the key facilities of Binary WorkStation:
  1941.  
  1942.      Modes
  1943.      -----
  1944.      There are two overall modes, INSERT ON and INSERT OFF.  When insert is ON,
  1945.      each keystroke will add a character or insert one where the cursor is. 
  1946.      When insert is OFF if there is a character where the cursor is, it will be
  1947.      struck over.
  1948.  
  1949.      Line Wrap
  1950.      ---------
  1951.      As opposed to word processing editors, there is no line wrap.  You can keep
  1952.      typing to the allowable width of the line, 256 characters.  Use the ENTER
  1953.      key to terminate the line.  For a more complete explanation refer to the
  1954.      Binary WorkStation section in this manual.
  1955.  
  1956.      Bottom Line Menu
  1957.      ----------------
  1958.      Binary Workstation uses a bottom line menu.  That is the bottom line of the
  1959.      screen lists the functions that will be executed when the respective
  1960.  
  1961.  
  1962.                                        Tutorial
  1963.                                           19
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.      function key is pressed.  A new set of functions is displayed when F10 is
  1972.      pressed and the previous set is displayed when F9 is pressed.  Any function
  1973.      may be executed, regardless of what is displayed, by pressing its
  1974.      associated key.  For example CNTL Q runs the program. 
  1975.  
  1976.  
  1977.  
  1978.                                       PROC LOAD
  1979.                                       ---------
  1980.  
  1981.      PROC LOAD is the procedure that is always executed first.  It is used to
  1982.      initialize conditions for the program, open files, etc.   
  1983.  
  1984.      Coding PROC LOAD
  1985.      ----------------
  1986.      In this example, PROC LOAD will open the data file.  If it cannot open the
  1987.      data file then it will assume that the data file is not there and create
  1988.      it.  In later sections we will make PROC LOAD a little smarter.  
  1989.  
  1990.      Type the lines show below which are boldfaced.
  1991.  
  1992.      PROC LOAD
  1993.                Procedure executed at the time the program loads.
  1994.  
  1995.      OPEN "CUST.DAT" USING "CUST.FID"  , 1:NO_FILE
  1996.                Open a file named CUST.DAT.  Use the data dictionary or FID,
  1997.                CUST.FID.  From now on we will refer to this file by the number
  1998.                1.  If successful, execute the next sequential command.  On
  1999.                error(i.e. could not open the file, possibly because it has not
  2000.                been created yet.) go to NO_FILE.  You may specify drives and/or
  2001.                paths in the file name,  e.g.  "/Q-PRO 4/CUST.DAT".
  2002.       
  2003.      END
  2004.                The data file was opened successfully.  The END statement gives
  2005.                control to the operator in the first enterable field. 
  2006.  
  2007.      :NO _FILE   MAKE "CUST.DAT" USING "CUST.FID",1:BAD
  2008.  
  2009.                Create CUST.DAT.  Structure it in accordance with the
  2010.                specifications in the data dictionary CUST.FID.  Assign it file
  2011.                number 1.  When created, go to the next sequential statement.  If
  2012.                it cannot be created, GOTO BAD and report the problem.
  2013.  
  2014.      END  
  2015.                On successful MAKE, turn over control to the operator.
  2016.  
  2017.      :BAD ERROR "UNABLE TO CREATE FILE"
  2018.  
  2019.                The ERROR command displays the message in quotes on line 24 of
  2020.  
  2021.  
  2022.                                        Tutorial
  2023.                                           20
  2024.  
  2025.  
  2026.  
  2027.  
  2028.  
  2029.  
  2030.  
  2031.                the screen. When the operator presses any key, control goes to
  2032.                the next sequential statement. 
  2033.  
  2034.      SYSTEM
  2035.                Although this statement will normally return you to the operating
  2036.                system, when you run the program from Binary WorkStation, your
  2037.                program will be reloaded ready for editing.
  2038.  
  2039.      END
  2040.                End of procedure.  Turn over control to the operator.
  2041.  
  2042.       
  2043.      Your proc should look like this:
  2044.  
  2045.      PROC LOAD
  2046.           FORMLOAD
  2047.           OPEN "CUST.DAT" USING "CUST.FID",1:NO
  2048.           END
  2049.      :NO MAKE "CUST.DAT" USING "CUST.FID",1:BAD
  2050.           END
  2051.      :BAD ERROR "UNABLE TO CREATE FILE"
  2052.                SYSTEM
  2053.                END
  2054.  
  2055.  
  2056.      Labels
  2057.      ------
  2058.      Labels, in Q-PRO 4, are simply places to jump to on various conditions. 
  2059.      They may be numeric or alphanumeric.  If they are alphanumeric, they follow
  2060.      the standard naming conventions discussed in the reference section. 
  2061.      Alphanumeric labels must have a colon (:) as the first character.
  2062.  
  2063.  
  2064.                                       PROC NAMEP
  2065.                                       ----------
  2066.  
  2067.      Function of the PROC
  2068.      --------------------
  2069.      When the user entirely fills the NAME field or presses TAB this PROC will
  2070.      execute.  It searches the database established in PROC LOAD and displays a
  2071.      customer record if there is a record on the file that exactly matches the
  2072.      name that is entered in the NAME FIELD.  
  2073.  
  2074.      Type only those lines which are boldfaced in the following procedure.
  2075.  
  2076.      PROC NAMEP  
  2077.                Defines the PROCedure NAMEP.
  2078.      POSN 1 TO NAME
  2079.                This statement positions the datafile to the contents of the
  2080.  
  2081.  
  2082.                                        Tutorial
  2083.                                           21
  2084.  
  2085.  
  2086.  
  2087.  
  2088.  
  2089.  
  2090.  
  2091.                screen data field, NAME.
  2092.  
  2093.      READ 1:NO_MATCH
  2094.                Read the record.  If there is an exact match between the file
  2095.                data field and the screen data field, load the file buffer with
  2096.                the record and execute the next command.  If there is not an
  2097.                exact match, go to NO_MATCH.
  2098.                For the purposes of retrieving a record from a file, an Exact
  2099.                match is understood to be a match, character by character, for
  2100.                both fields.
  2101.  
  2102.           COPY 1 TO *
  2103.                Copy all fields on the data file that have the same name as
  2104.                fields on the screen to the screen.  The 1 is the file number and
  2105.                the asterisk (*) is used to represent the screen.  This is one of
  2106.                the ways a data dictionary can work for you.  By simply selecting
  2107.                matching, or non-matching names, you can easily control what data
  2108.                is copied from what to what.  Of course, you can specify the
  2109.                movement a field at a time if you wish.
  2110.  
  2111.           NEXT
  2112.                Gives the operator control in the next enterable field, STREET.
  2113.  
  2114.                NOTE:  Other Q-PRO 4 statements that give control back to the
  2115.                operator are END, and RESUME.
  2116.  
  2117.      :NO_MATCH END
  2118.                If there is no matching record on the database terminate the
  2119.                PROC.  This gives control to the user in the next enterable
  2120.                field, STREET.  
  2121.  
  2122.      Your PROC should look like this:
  2123.  
  2124.      PROC NAMEP
  2125.                POSN 1 TO NAME
  2126.                READ 1:NO_MATCH
  2127.                COPY 1 TO *
  2128.                NEXT
  2129.      :NO_MATCH
  2130.  
  2131.      END
  2132.  
  2133.                                     Event Driving
  2134.                                     -------------
  2135.  
  2136.      The event which sets off looking for a particular name on file, i.e.
  2137.      executing PROC NAME, is the operator leaving the screen data field, NAME. 
  2138.      Normally the operator presses the TAB key.
  2139.  
  2140.  
  2141.  
  2142.                                        Tutorial
  2143.                                           22
  2144.  
  2145.  
  2146.  
  2147.  
  2148.  
  2149.  
  2150.  
  2151.      The Linkage
  2152.      -----------
  2153.      We need to establish the linkage between the event, i.e. tabbing out of
  2154.      screen data field NAME and executing PROC NAME.  The linkage is established
  2155.      as part of the field definition of the screen data field, NAME.  We will
  2156.      set this up now.
  2157.  
  2158.      Adding the Linkage
  2159.      ------------------
  2160.      From the program code editor, press SHIFT F8 to load the screens editor.
  2161.  
  2162.      The screen format that you've been working on will display.  Place the
  2163.      cursor on the #####'s after Name and press F1.  The Field Definition Screen
  2164.      will display.  
  2165.  
  2166.      Move the cursor to the right of the field NAME:.  Place it on the number
  2167.      signs (###), and press F1.  The FIELD FORMAT DEFINITION for the screen data
  2168.      field NAME will be displayed.  
  2169.  
  2170.      Tab to the right under Proc Name.  Type NAMEP.  This is the linkage to the
  2171.      interpreter.  When the operator presses TAB in the screen data field NAME,
  2172.      Q-PRO 4 sees NAMEP as the screen field procedure name and it looks for a
  2173.      procedure in the program code named NAMEP to execute some instructions.  If
  2174.      there is no procedure named NAMEP, an error will be reported.  You can't
  2175.      fool Q-PRO 4!
  2176.  
  2177.      Press ESC twice to return to the program code editor.
  2178.  
  2179.  
  2180.                                     Recording Data
  2181.                                     --------------
  2182.      PROC ENTER
  2183.      ----------
  2184.      This proc is executed when the designated ENTER key is pressed.  Most
  2185.      often, it is used when the data on screen is complete and the user wishes
  2186.      to record it.
  2187.  
  2188.      PROC ENTER
  2189.           This is the procedure invoked when the ENTER key is pressed. 
  2190.  
  2191.      COPY * TO 1
  2192.           Copy all the screen data fields to the file data fields of the same
  2193.           name. 
  2194.  
  2195.      WRITE 1 NOADV : BAD_WRITE
  2196.           Write the record, goto BAD_WRITE on error.  The NOADV keeps the file
  2197.           from advancing to the next record which saves time.   It is important
  2198.           to note here what gets written when this command is executed.  In the
  2199.           current example, the contents of the screen will be recorded on disk. 
  2200.  
  2201.  
  2202.                                        Tutorial
  2203.                                           23
  2204.  
  2205.  
  2206.  
  2207.  
  2208.  
  2209.  
  2210.  
  2211.           Because the key to the file is NAME, if you have entered a new name
  2212.           then a new record will be created.  If it is a name that is already on
  2213.           file, then that record will be updated to match the screen.
  2214.  
  2215.      END
  2216.           The screen will clear.  (This is automatic when the ENTER command
  2217.           reaches the END statement.)  Control is turned over to the operator in
  2218.           the CUSTNO field.
  2219.  
  2220.      :BAD_WRITE  ERROR "ERROR IN WRITING RECORD"
  2221.           Display the error message "ERROR IN WRITING RECORD" on line 24.  Turn
  2222.           over control to the operator until the ESC key is pressed.  When ESC
  2223.           is pressed, the next command will execute.
  2224.  
  2225.      SYSTEM
  2226.           Return to the operating system.
  2227.  
  2228.      END
  2229.           Here, the END is not really needed, but putting it in is good
  2230.           procedure.
  2231.  
  2232.      Your PROC should look like this:
  2233.  
  2234.      PROC ENTER
  2235.           COPY * TO 1 
  2236.           WRITE 1:BAD_WRITE
  2237.           END
  2238.      :BAD_WRITE     ERROR "ERROR IN WRITING RECORD"
  2239.           SYSTEM
  2240.           END 
  2241.  
  2242.  
  2243.      Running the Program
  2244.      -------------------
  2245.      Press CNTL U to update the program.  When the dialog screen displays, press
  2246.      ENTER.  Press CNTL Q.  When the dialog screen displays, press ENTER.
  2247.  
  2248.      Entering Data
  2249.      -------------
  2250.      Enter a name in the Customer field.  If the customer is already on the
  2251.      database, it will be retrieved from the file and displayed.  You can enter
  2252.      it as is or correct it and enter it.  
  2253.      ESC will return you to Binary WorkStation procedural code editor.
  2254.  
  2255.  
  2256.                                Finding and Fixing Bugs
  2257.                                -----------------------
  2258.  
  2259.      Returning to Binary Workstation
  2260.  
  2261.  
  2262.                                        Tutorial
  2263.                                           24
  2264.  
  2265.  
  2266.  
  2267.  
  2268.  
  2269.  
  2270.  
  2271.      -------------------------------
  2272.      Press ESC, which will bring you back to Binary WorkStation's program code
  2273.      editor.
  2274.  
  2275.      Correcting Screen data fields
  2276.      ----------------------------
  2277.      To change a screen data field, redisplay the field and change it by placing
  2278.      the cursor anywhere on the number signs and press F1.  The field definition
  2279.      screen will be displayed with the previous entries.
  2280.  
  2281.      You may change any of them by moving the cursor with the TAB key and making
  2282.      the change.  Press ENTER to return to the data entry screen.
  2283.  
  2284.      Syntax Checker
  2285.      --------------
  2286.      With the Binary WorkStation loaded, press CNTL W.  Your program will be
  2287.      checked for correct syntax.
  2288.  
  2289.      If any errors are found, the syntax checker will stop at the first one. 
  2290.      Use the editing keys INSERT CHARACTER, DELETE CHARACTER, INSERT LINE, and
  2291.      DELETE LINE, etc to correct the error.
  2292.  
  2293.      Press CNTL W again.  Continue to syntax check and correct until no more
  2294.      syntax errors are detected.
  2295.  
  2296.      Line Numbers
  2297.      ------------
  2298.      Binary WorkStation does not use line numbers to organize itself.  The line
  2299.      numbers are normally not even displayed.  They are used as an aid to
  2300.      debugging.  When an error is reported by the interpreter, it will refer to
  2301.      a line number.  You can display the line numbers with Binary Workstation to
  2302.      find the offending line of code.
  2303.  
  2304.      Labels
  2305.      ------
  2306.      Numeric and alphanumeric labels are merely labels to jump to.  However,
  2307.      remember that a label can be jumped to even if it is not within the
  2308.      procedure that references it.
  2309.  
  2310.  
  2311.                           Adding Programmable Function Keys
  2312.                            --------------------------------
  2313.  
  2314.      General Description
  2315.      -------------------
  2316.      Q-PRO 4 recognizes 21 programmable function keys, 0 to 20.  Each key is
  2317.      associated with a specific PROC, PROC KEY0-20.  The PROC associated with
  2318.      the key executes immediately.  For example, on the IBM PC, pressing
  2319.      function key, F1 executes the proc KEY1; PROC KEY11 is invoked with Shift
  2320.  
  2321.  
  2322.                                        Tutorial
  2323.                                           25
  2324.  
  2325.  
  2326.  
  2327.  
  2328.  
  2329.  
  2330.  
  2331.      F1.  
  2332.  
  2333.      Functionality
  2334.      -------------
  2335.      The proc can do anything you wish it to do.  Some of the more common uses
  2336.      are:  advancing and backspacing a single record in a file, deleting
  2337.      records, special searches, and chaining to other screens.
  2338.  
  2339.      Pre-defined Function Key
  2340.      ------------------------
  2341.      PROC KEY0 is pre-defined with the following code:
  2342.  
  2343.           CLOSE
  2344.           SYSTEM
  2345.           END
  2346.  
  2347.      It is invoked with the ESC key.  You need not define it if closing the
  2348.      files and going to the operating system are what you want it to do. 
  2349.      Otherwise program this key as any other.   
  2350.  
  2351.      Examples
  2352.      --------
  2353.      We suggest that you add the examples below to your program to enhance its
  2354.      functionality.
  2355.  
  2356.      First let's write a simple subroutine that will save us some time later. 
  2357.      This subroutine reads and displays a record.
  2358.  
  2359.  
  2360.  
  2361.      PROC KEY_READ
  2362.           READ 1:EF
  2363.                Advance the file pointer one record.  If there is an error,
  2364.                presumably an End of File, goto EF.
  2365.  
  2366.           COPY 1 TO *
  2367.                Copy the fields with the same names in the data file as on the
  2368.                screen to the screen.
  2369.  
  2370.           RETURN
  2371.                Return to the main program at the next instruction after the
  2372.                calling statement.
  2373.  
  2374.      :EF  ERROR "No more records" 
  2375.                RETURN
  2376.  
  2377.      Example: Display Next Record
  2378.  
  2379.      PROC KEY1
  2380.  
  2381.  
  2382.                                        Tutorial
  2383.                                           26
  2384.  
  2385.  
  2386.  
  2387.  
  2388.  
  2389.  
  2390.  
  2391.           CALL KEY_READ
  2392.           END
  2393.           This example takes advantage of the characteristics of an indexed
  2394.           file.  The READ command will advance the file one logical record in
  2395.           the logical sequence or key. 
  2396.  
  2397.      Example: Display Previous Record
  2398.  
  2399.      PROC KEY2
  2400.           BACKSPACE 1:EF
  2401.           BACKSPACE 1:EF
  2402.                When a record is read, the record pointer is pointing to the next
  2403.                record.  Therefore to backspace preparing to read the previous
  2404.                record, you must backspace twice.  We have used the end of file
  2405.                routine from PROC KEY1 which it won't mind.  
  2406.        
  2407.           CALL KEY_READ
  2408.           END
  2409.  
  2410.      Example:  Delete the Currently Displayed Record
  2411.  
  2412.      PROC KEY11
  2413.           POSN 1 TO NAME USING 1
  2414.                Position the file to the contents of NAME in the primary key.  We
  2415.                want to insure that in all circumstances the record to be deleted
  2416.                actually exists. 
  2417.       
  2418.           CALL KEY_READ
  2419.  
  2420.                If the record does not exist, then the READ statement in KEY_READ
  2421.                will cause the file to go to end of file.  
  2422.  
  2423.           FREE 1
  2424.                The record currently in the buffer, i.e. the one just read, will
  2425.                be marked deleted.  This logically removes the record from the
  2426.                database.
  2427.           END
  2428.  
  2429.  
  2430.                                 Partial Key Searching
  2431.                                 ---------------------
  2432.  
  2433.      Capabilities
  2434.      ------------
  2435.      One of the more powerful features of Q-PRO 4 is partial key searching. 
  2436.      This feature allows you to get the "nearest" match for a key search.
  2437.  
  2438.      Now you can look up a customer name if you only know the first letter of
  2439.      the name.  For those of us who have occasional memory lapses, this is the
  2440.  
  2441.  
  2442.                                        Tutorial
  2443.                                           27
  2444.  
  2445.  
  2446.  
  2447.  
  2448.  
  2449.  
  2450.  
  2451.      greatest.  If you can't remember without seeing the whole record whether it
  2452.      is Smith, Smithson, or Smyth.  
  2453.  
  2454.      As an example, in our customer program, with partial key searching you just
  2455.      type "Sm" and press a function key.  The record for Smith will be
  2456.      displayed.  Using the next and previous function keys lets you browse the
  2457.      data.  
  2458.  
  2459.      Example: Partial Key Searching
  2460.  
  2461.      PROC KEY3
  2462.           POSN 1 TO NAME RELATIVE 
  2463.                The RELATIVE modifier tells Q-PRO 4 to search for an exact match
  2464.                for the contents of the screen data field, NAME, or the nearest
  2465.                next higher match.  Therefore an entry of Sm will bring up the
  2466.                first of the series.
  2467.  
  2468.           CALL KEY_READ
  2469.           END 
  2470.  
  2471.      Example: Position to Beginning of File
  2472.      PROC KEY7
  2473.           POSN 1 TO  "" RELATIVE
  2474.                Positioning the file to a null (double quotes, single or double,
  2475.                with no space between them) RELATIVE  positions it to the first
  2476.                record of the file.
  2477.  
  2478.  
  2479.  
  2480.  
  2481.  
  2482.  
  2483.  
  2484.  
  2485.  
  2486.  
  2487.  
  2488.  
  2489.  
  2490.  
  2491.  
  2492.  
  2493.  
  2494.  
  2495.  
  2496.  
  2497.  
  2498.  
  2499.  
  2500.  
  2501.  
  2502.                                        Tutorial
  2503.                                           28
  2504.  
  2505.  
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.                                Hints, Tips & Techniques
  2512.                               =========================
  2513.  
  2514.  
  2515.      Inherent Structure
  2516.      ------------------
  2517.      Because Q-PRO 4's PROC's are inherently structured, there is not much to do
  2518.      to organize your programs.  However, you might find it helpful to group
  2519.      various type of procs such as function key procs, subroutines, etc.
  2520.      together with an appropriate section heading.  If you use an asterisk to
  2521.      preface the heading, Q-PRO 4 will think it is a comment.  An example of
  2522.      this technique:
  2523.  
  2524.      * * * * * * * *  Field Procedures * * * * * * * * * * * 
  2525.  
  2526.      PROC NAMEP
  2527.                POSN 1 TO NAME
  2528.                READ 1:NO_MATCH
  2529.                COPY 1 TO *
  2530.                NEXT
  2531.      :NO_MATCH END
  2532.  
  2533.  
  2534.      * * * * * * * * Function Key Procedures * * * * * * * * * 
  2535.  
  2536.      PROC KEY1
  2537.           CALL KEY_READ
  2538.           END
  2539.  
  2540.      PROC KEY2
  2541.           BACKSPACE 1:EF
  2542.           BACKSPACE 1:EF
  2543.           CALL KEY_READ
  2544.           END
  2545.  
  2546.      PROC KEY11
  2547.           POSN 1 TO NAME USING 1
  2548.           CALL KEY_READ
  2549.           FREE 1
  2550.           END
  2551.  
  2552.  
  2553.                                    Sample Programs
  2554.                                    ---------------
  2555.  
  2556.      Using the Sample Programs
  2557.      -------------------------
  2558.      The sample programs comprise a demonstration invoicing system including the
  2559.      programs and some sample data.  The programs are designed to demonstrate
  2560.  
  2561.  
  2562.                                        Tutorial
  2563.                                           29
  2564.  
  2565.  
  2566.  
  2567.  
  2568.  
  2569.  
  2570.  
  2571.      some overall technique of programming with Q-PRO 4.  As demonstrations,
  2572.      they are not necessarily the best code for they were developed to
  2573.      demonstrate certain functions.  We recommend that you run them and look at
  2574.      the code.
  2575.  
  2576.      You may create your own data or use the sample data provided.  SAMPINS.DAT
  2577.      and SAMPINS.FID must be on the same directory as  the program files.  All
  2578.      other data and the FID files may be on any directory as long as all reside
  2579.      in the same directory.
  2580.  
  2581.      SAMPINS.QNE    You must run this program first.  It sets up the application
  2582.                     control file.  In this program you use a one record random
  2583.                     file to specify the system parameters such as:
  2584.  
  2585.                     o Password (and its encryption) 
  2586.                     o Company name and address
  2587.                     o Operating system
  2588.                     o Host
  2589.                     o Path for data files and FID files
  2590.  
  2591.                If the HOST and the operating system are not set correctly, then
  2592.                things will not work right.
  2593.  
  2594.      SAMPMAKE.QNE   This program is chained to from SAMPINS.QNE.  Use it to
  2595.                     create new data files.  If you create data files, the sample
  2596.                     files furnished will be deleted.  It illustrates:
  2597.  
  2598.                     o Safely creating data files
  2599.                     o Operator-program dialog
  2600.                     o Use of application control file parameters           
  2601.  
  2602.      SAMPMENU.QNE   This is the main menu for the program.  It illustrates:
  2603.  
  2604.                     o How to use the application control file for determining
  2605.                     the HOST, operating system and where the data and FID files
  2606.                     are. 
  2607.                     o How to get and use a password from the user.
  2608.                     o How to determine if the password has already been given so
  2609.                     it will not be asked for again.
  2610.                     o Chaining to other programs.   
  2611.       
  2612.      SAMPCUST.QNE   This program maintains the customer database.  From it you
  2613.                     can add a new customer, change a customer or delete a
  2614.                     customer.  It illustrates:
  2615.  
  2616.                     o Determining if a file is already open before attempting to
  2617.                     open it.
  2618.                     o Scrolling forward and backward in a data file by either of
  2619.                     two keys. 
  2620.  
  2621.  
  2622.                                        Tutorial
  2623.                                           30
  2624.  
  2625.  
  2626.  
  2627.  
  2628.  
  2629.  
  2630.  
  2631.                     o Duplicating repetitive data without rekeying.
  2632.  
  2633.      SAMPROD.QNE    This program maintains the product data base.  Use it to
  2634.                     add, delete or change products.  It illustrates:
  2635.                     o Determining if a file is already open before attempting to
  2636.                     open it.
  2637.                     o Scrolling forward and backward in a data file by either of
  2638.                     two keys. 
  2639.  
  2640.      SAMPEN.QNE     This program is the first of two programs that write an
  2641.                     invoice.  It is used to put in the bill head information. 
  2642.                     It illustrates:
  2643.                     o Use of the application control file to assign invoice
  2644.                     numbers.
  2645.                     o Use of PROC BREAK.
  2646.                     o Using multiple screens to enter data to one file.
  2647.  
  2648.      SAMPEN1.QNE    This is the second program for writing an invoice.  It
  2649.                     creates the line items of the invoice.  It illustrates:
  2650.                     o Screen scrolling
  2651.                     o Printing from Q-PRO 4 (as opposed to the report generator)
  2652.                     o Multiple records for a screen
  2653.  
  2654.  
  2655.                                 Advanced Input Editing
  2656.                                 ----------------------
  2657.  
  2658.      Capabilities
  2659.      ------------
  2660.      The only limit on the ways you can edit data as it is input is your
  2661.      imagination.  Some of the more common methods are:
  2662.  
  2663.           o Range checks
  2664.           o Table lookup
  2665.           o Comparison to other fields
  2666.           o File lookup
  2667.  
  2668.      Screen Data Field Edit Example:
  2669.           Range check of the screen data field, ZIP.
  2670.  
  2671.      PROC RANGE
  2672.           IF ZIP GE 10000 AND ZIP LE 90000 END
  2673.                End the procedure if the Zip code is in the range  10000 to
  2674.                90000. (GE = greater than or equal to, LE = less than or equal
  2675.                to.)
  2676.  
  2677.           ERROR "ZIP  outside Range."
  2678.                 Put a message on line 24 for the operator.
  2679.  
  2680.  
  2681.  
  2682.                                        Tutorial
  2683.                                           31
  2684.  
  2685.  
  2686.  
  2687.  
  2688.  
  2689.  
  2690.  
  2691.           CLEAR $FIELD[#F]
  2692.                Clear the current screen data field.  The function,
  2693.                $FIELD[<expression>], refers to the screen data field whose
  2694.                offset is calculated in the <expression>.  A screen data field's
  2695.                offset is the number of fields from the first screen data field
  2696.                (whose offset is zero) counting from left to right, top to
  2697.                bottom.  One of the valid arguments in the expression is #F, the
  2698.                current screen data field offset.  
  2699.  
  2700.           RESUME
  2701.                Give control back to the operator in the current field.
  2702.  
  2703.      Screen Data Field Edit Example: 
  2704.           Table look up of the verification of the screen data field, State
  2705.  
  2706.      PROC TABLE_LOOK
  2707.           TSEAR OK_STATES AT STATE:NO_ST
  2708.                Search the table OK_STATES using the contents of the field,
  2709.                STATE.  If there is a match, goto the next command.  If there is
  2710.                no match, goto NO_ST.
  2711.           END
  2712.                Found  a  match, end proc.
  2713.  
  2714.      :NO_ST    ERROR "Don't use this state. "
  2715.                Display instructions on line 24 of the CRT.
  2716.  
  2717.           RESUME
  2718.  
  2719.           TABLE OK_STATES
  2720.                "PA"
  2721.                "CA"
  2722.                "DE"
  2723.            END
  2724.  
  2725.                This table specifies only these three states.
  2726.  
  2727.      Screen Data Field Edit Example:
  2728.           Comparisons between fields.
  2729.  
  2730.      PROC COMPARE
  2731.           IF STATE = "PA" AND ZIP LT 50000 GOTO ST_ERR
  2732.                If the contents of the screen data field, STATE, is "PA" and the
  2733.                contents of the screen data field, ZIP, is less than 50000, goto
  2734.                the label ST_ERR
  2735.  
  2736.      Screen Data Field Edit Example:
  2737.           File verification of the field, ZIP.
  2738.  
  2739.      PROC FILE_CHK
  2740.  
  2741.  
  2742.                                        Tutorial
  2743.                                           32
  2744.  
  2745.  
  2746.  
  2747.  
  2748.  
  2749.  
  2750.  
  2751.           POSN 1 TO ZIP USING 2
  2752.                Change the file key of file 1 to the second key, ZIP. (You will
  2753.                see how to change file structures to put in additional keys in a
  2754.                later section.)  Position file 1 to the contents of the screen
  2755.                data field, ZIP.
  2756.  
  2757.           READ 1:NO_ZIP
  2758.                Read file 1.  If there is an exact match, execute the next
  2759.                sequential command.  If there is no exact match, goto NO_ZIP.
  2760.  
  2761.           KEY 1 USING 1
  2762.                Set the key back to the primary key.
  2763.           END
  2764.  
  2765.      :NO_ZIP  ERROR "This ZIP CODE is not authorized"
  2766.                CLEAR $FIELD[#F]
  2767.                KEY 1 USING 1
  2768.                RESUME
  2769.  
  2770.  
  2771.  
  2772.                                    Screen Handling
  2773.                                    ---------------
  2774.  
  2775.      Screen Graphics
  2776.      ---------------
  2777.      For certain systems (as noted in the quick reference card paste-ins), block
  2778.      or business graphics are available for enhancing the screen presentation. 
  2779.      Scrolling the Binary WorkStation menu in the screen editor mode allows
  2780.      turning graphics mode on.  While in the graphics mode the function keys
  2781.      function as shown below:
  2782.  
  2783.           CURSOR LEFT, RIGHT  HORIZONTAL SEGMENT
  2784.           CURSOR UP, DOWN     VERTICAL SEGMENT
  2785.           FUNCT 9   T RIGHT
  2786.           FUNCT 8   T LEFT
  2787.           FUNCT 7   T DOWN
  2788.           FUNCT 6   T UP
  2789.           FUNCT 5   CENTER CROSS
  2790.           FUNCT 4   LOWER RIGHT CORNER
  2791.           FUNCT 3   LOWER LEFT CORNER
  2792.           FUNCT 2   UPPER RIGHT CORNER
  2793.           FUNCT 1   UPPER LEFT CORNER
  2794.           FUNCT 10  TOGGLE GRAPHICS MODE ON/OFF
  2795.  
  2796.  
  2797.      Screen Data Fields - Editing Rows and Columns
  2798.      ---------------------------------------------
  2799.      Row/Column coordinates are usually skipped after entering the FIELD NAME. 
  2800.  
  2801.  
  2802.                                        Tutorial
  2803.                                           33
  2804.  
  2805.  
  2806.  
  2807.  
  2808.  
  2809.  
  2810.  
  2811.      When you skip these fields, Binary WorkStation calculates the coordinates
  2812.      for you.
  2813.  
  2814.      The coordinates may be "forced" by entering the actual coordinates.  This
  2815.      is useful for moving a variable field to another place on the screen to
  2816.      quickly customize a display.
  2817.  
  2818.      Correcting Screen Data Fields
  2819.      -----------------------------
  2820.      To change a screen data field, redisplay the field and change it by placing
  2821.      the cursor anywhere on the number signs and press F1.  The field definition
  2822.      screen will be displayed with the previous entries.
  2823.  
  2824.      You may change any of them by moving the cursor with the TAB key and making
  2825.      the change.  Press ENTER to return to the data entry screen.
  2826.  
  2827.      Screen Offset
  2828.      -------------
  2829.      The screen offset allows the programmer to address the screen data fields
  2830.      as offsets from the first screen data field.  Thus, the programmer may
  2831.      symbolically select fields on the screen according to the program logic or
  2832.      table look-up.
  2833.  
  2834.      The offset value for each screen data field is shown on the program
  2835.      listing.  It is no more than the number of fields from the first screen
  2836.      data field counting from left to right, top to bottom.  With this logic,
  2837.      the first screen data field at the upper left has an offset of 0. The one
  2838.      next to it on the same line has an offset of 1, etc.
  2839.  
  2840.      The field is addressed by the function $FIELD.  $FIELD allows handling of
  2841.      fields on the screen by offset value without worrying about the name of the
  2842.      field.  The combination of loops, registers and tables provides
  2843.      extraordinary screen handling capability.
  2844.  
  2845.      Example: 
  2846.  
  2847.      MOVE $FIELD[6] TO $FIELD[7]
  2848.           This moves the sixth field on the screen (counting from the top left
  2849.           field on the screen and going from left to right, top to bottom,
  2850.           starting with field zero) to the seventh field.
  2851.  
  2852.      Example:  scrolling upwards on the screen.
  2853.  
  2854.      Using the following screen format:
  2855.  
  2856.      Field 0   ###########   Field 1  ###########
  2857.      Field 2   ###########   Field 3  ###########
  2858.  
  2859.      FOR #N0 = 0 TO 1
  2860.  
  2861.  
  2862.                                        Tutorial
  2863.                                           34
  2864.  
  2865.  
  2866.  
  2867.  
  2868.  
  2869.  
  2870.  
  2871.           Begins a FOR loop from 0 to 1
  2872.           MOVE $FIELD[#N0+2] TO $FIELD[#N0]
  2873.                Moves FIELD 2 (#N0 plus 2) to FIELD 0.  Then moves FIELD 3 to
  2874.                FIELD 1.
  2875.  
  2876.      ENDFOR #N0
  2877.           END
  2878.                Note that in the contents of the brackets following the $FIELD
  2879.                will be evaluated as an expression.  This expression must
  2880.                evaluate to an integer.  The following (assuming that the
  2881.                contents of the numeric register are integers) are all valid:
  2882.  
  2883.           $FIELD[(#N1 * #N2) + 10]
  2884.           $FIELD[#N1 + #N2 - 20]
  2885.           $FIELD[$OFFSET(SCNFIELD) + 5]
  2886.  
  2887.  
  2888.      #F - The Screen Field Offset Register
  2889.      -------------------------------------
  2890.      The register #F always contains the offset of the current screen data
  2891.      field.  It uses are numerous.  For example, to call a help screen for a
  2892.      particular screen field, you can use this instruction:
  2893.  
  2894.      IF #F EQ 8 HELP "FIELD"
  2895.           #F provides powerful screen handling when combined with $FIELD.  For
  2896.           example, to clear the current field and the next three fields, use
  2897.           this code:
  2898.  
  2899.      FOR #N1 = 0 TO 2
  2900.           CLEAR $FIELD[#F + #N1]
  2901.      ENDFOR #N1
  2902.  
  2903.      Screen Data Fields Using the Same Procedure
  2904.      -------------------------------------------
  2905.      Many screen data fields may use a common procedure.  As an example of the
  2906.      use of this technique, suppose you want to add a column of three fields and
  2907.      want the correct total always to be displayed on the fourth line even if
  2908.      the user backtabs and changes the number.  The obvious is to go through a
  2909.      long series of steps to subtract out the previous number, maintain the
  2910.      values in an array or something else very tedious.  
  2911.  
  2912.      The four fields are:
  2913.  
  2914.      ADD1     ##########
  2915.      ADD2     ##########
  2916.      ADD3     ##########
  2917.  
  2918.      RESULT  ##########
  2919.  
  2920.  
  2921.  
  2922.                                        Tutorial
  2923.                                           35
  2924.  
  2925.  
  2926.  
  2927.  
  2928.  
  2929.  
  2930.  
  2931.      Make RESULT non-enterable and use this PROC for the fields ADD1, ADD2, and
  2932.      ADD3:
  2933.  
  2934.      PROC ADDP
  2935.           CLEAR RESULT
  2936.           MOVE $OFFSET(ADD1) TO #N2
  2937.      *  The function $OFFSET gives the offset of the field ADD1.
  2938.  
  2939.           FOR #N1 = 0 TO 2
  2940.                ADD $FIELD[#N2 + #N1] TO RESULT
  2941.           ENDFOR #N1
  2942.  
  2943.           With this routine, it makes no difference which field or in which
  2944.           order the data is entered, the result will be correct.
  2945.  
  2946.  
  2947.                                 Structured Programming
  2948.                                 ----------------------
  2949.  
  2950.      Structured Constructs
  2951.      ---------------------
  2952.      Q-PRO 4 has an excellent set of structured constructs.  This set is
  2953.      initiated with the command, BEGIN.  BEGIN is modified by IF, WHILE, or
  2954.      UNTIL followed by a condition.  The BEGIN construct will be entered under
  2955.      these conditions:
  2956.  
  2957.      BEGIN IF <condition>
  2958.           Enter and execute all commands between the BEGIN and ENDBEGIN if the
  2959.           <condition> is true.  If the <condition> is not true, skip over the
  2960.           construct.  (See also ELSE and ELSE IF.)
  2961.  
  2962.      BEGIN WHILE<condition>
  2963.           Enter the construct and repeatedly execute the commands within it as
  2964.           long as the <condition> is true.
  2965.  
  2966.      BEGIN UNTIL<condition>
  2967.           Enter the construct and repeatedly execute the commands within it
  2968.           until the <condition> becomes true.7
  2969.  
  2970.      The BEGIN construct is terminated by ENDBEGIN.  Between the BEGIN and the
  2971.      ENDBEGIN are the commands to be executed if the BEGIN construct is entered.
  2972.  
  2973.      Examples:
  2974.  
  2975.      BEGIN IF A > B
  2976.           CALL SUB1
  2977.           CALL SUB2
  2978.      ENDBEGIN
  2979.  
  2980.  
  2981.  
  2982.                                        Tutorial
  2983.                                           36
  2984.  
  2985.  
  2986.  
  2987.  
  2988.  
  2989.  
  2990.  
  2991.      BEGIN WHILE A < 10
  2992.           CALL TEST_SUB
  2993.           ADD 1 TO A
  2994.      ENDBEGIN
  2995.                The subroutine TEST_SUB will be repeatedly called until the
  2996.                variable A reaches the value of 10
  2997.  
  2998.      MOVE 0 TO A
  2999.      BEGIN UNTIL A=10
  3000.           CALL TEST_SUB
  3001.           ADD 1 TO A
  3002.      ENDBEGIN
  3003.           The subroutine TEST_SUB will repeatedly be called until the variable A
  3004.           reaches the value of 10.
  3005.  
  3006.      The BEGIN IF construct may also include ELSE and/or ELSE IF prior to the
  3007.      ENDBEGIN.
  3008.        
  3009.      Example:
  3010.      BEGIN IF  A=B
  3011.                CALL SUBA
  3012.           ELSE IF A=C
  3013.                CALL SUBB
  3014.           ELSE
  3015.                CALL SUBC
  3016.      ENDBEGIN
  3017.           If A=B, call subroutine A, if A=C call subroutine B; if it equals
  3018.           neither, call subroutine C.
  3019.  
  3020.  
  3021.                                       Debugging
  3022.                                       ---------
  3023.  
  3024.      Q-PRO 4 has a wealth of debugging tools that range from simply reloading
  3025.      the program and BW on an error to a full runtime debugger.
  3026.  
  3027.      ERROR Command
  3028.      -------------
  3029.      An ERROR command in the program code will halt execution and display the
  3030.      specified error message on line 24 of the CRT.  When the program encounters
  3031.      the ERROR command, it will stop, display the specified error message and
  3032.      wait for operator action.  For debugging, a message with the ERROR command
  3033.      can be used to identify locations in the code, etc.  Messages can be
  3034.      literals in quotes, a register, or a variable.
  3035.           
  3036.      DEBUG Command
  3037.      -------------
  3038.      The DEBUG command loads the runtime debugger.  It has a host of
  3039.      capabilities that include looking at any field, changing memory, changing
  3040.  
  3041.  
  3042.                                        Tutorial
  3043.                                           37
  3044.  
  3045.  
  3046.  
  3047.  
  3048.  
  3049.  
  3050.  
  3051.      the value of variables, and looking at the values of file fields.  For more
  3052.      detail on the use of DEBUG, refer to the Commands section.
  3053.  
  3054.  
  3055.  
  3056.      TRACE Command
  3057.      -------------
  3058.      The TRACE command will put the program in single step mode.  When TRACE is
  3059.      encountered, the program will execute one command at a time, displaying the
  3060.      command to be executed on line 24.  Pressing the ESCAPE key will execute
  3061.      the displayed command.  This will continue until the command NOTRACE is
  3062.      encountered or RETURN is pressed.
  3063.  
  3064.      If the "D" key is pressed during TRACE, the online debugger will be loaded
  3065.      after the command is executed.
  3066.  
  3067.  
  3068.                                  All About Registers
  3069.                                  -------------------
  3070.  
  3071.      General
  3072.      -------
  3073.      Registers are temporary working areas maintained by the system which
  3074.      resemble fields except that they are not displayed on the screen.  The
  3075.      contents of all data registers remain intact when you CHAIN to another
  3076.      application file.
  3077.  
  3078.      There are three types of data registers.  Each type has ten usable
  3079.      registers.  Registers are cleared when Q-PRO 4 is first loaded.  The
  3080.      current value of the register remains when one program CHAINs to another.
  3081.  
  3082.      String Registers
  3083.      ----------------
  3084.      String registers are used as temporary storage for data. For example, they
  3085.      can be used to build an output record for the printer or intermediate
  3086.      storage for input data prior to moving it to a field or output buffer. 
  3087.      They may be used as variables in any command in lieu of a field or literal. 
  3088.      Also, string registers are used to transfer variables between program
  3089.      chains.
  3090.  
  3091.      Length         255 Characters 
  3092.      Names          #S0 to #S9.  (the lower case "s" can be used)
  3093.      Clearing       MOVE "" or '' to the register 
  3094.                     Example:  MOVE "" TO #S0
  3095.                         or    MOVE '' TO #S0
  3096.  
  3097.      Rules for the Use of String Registers
  3098.      -------------------------------------
  3099.      1.   Data can be concatenated onto an existing string in a register or it
  3100.  
  3101.  
  3102.                                        Tutorial
  3103.                                           38
  3104.  
  3105.  
  3106.  
  3107.  
  3108.  
  3109.  
  3110.  
  3111.      can be moved on top of existing data, but data cannot be moved to an
  3112.      arbitrary position within a register that has been cleared.  To move data
  3113.      into the register at random, first fill it with blanks.     
  3114.      2.   A string register may not be moved into a numeric register unless the
  3115.      string register contains valid numeric data.
  3116.  
  3117.  
  3118.           Note:     A MOVE command with the destination being a data register
  3119.                     clears the register of any data previously contained and
  3120.                     puts the new data in the register.    
  3121.  
  3122.      Numeric Registers
  3123.      -----------------
  3124.      Numeric registers are used the same as string registers, but limited to
  3125.      numeric data.
  3126.  
  3127.           Length         20 Digits 
  3128.           Name           #N0 to #N9
  3129.           Clearing       Move a zero (0) into the register
  3130.  
  3131.      Rules for the Use of Numeric Registers
  3132.      --------------------------------------
  3133.      1.   A string or string register can be moved into a numeric register only
  3134.      if the data is all numeric, [0-9  -  +  .]  (Note: decimal points move with
  3135.      numeric data.)
  3136.      2.   Numeric registers can always be moved to a string register or field.
  3137.      3.   No substring operations are allowed in numeric registers.
  3138.  
  3139.      Bit or Boolean Registers
  3140.      ------------------------
  3141.      Each Boolean register is a flag that can be interrogated by the program to
  3142.      see if it is on or off.  Program logic upon interrogating this flag will
  3143.      determine an action.  In other words they direct logical branches in a
  3144.      program.
  3145.  
  3146.           Length         Each boolean register is a single bit
  3147.           Name           #B0 to #B9
  3148.           Setting        SET #B0
  3149.           Clearing       RESET #B0
  3150.  
  3151.      Examples:
  3152.      IF #B0 SET LOCK FIELD
  3153.           If bit register is set (on) lock the field named FIELD.
  3154.  
  3155.      IF #B0 SET CALL SUB_ROUT1
  3156.           If bit register is set (on) call subroutine SUB_ROUT1.
  3157.  
  3158.      System Registers
  3159.      ----------------
  3160.  
  3161.  
  3162.                                        Tutorial
  3163.                                           39
  3164.  
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.       The system has several registers that it maintains.  They are:
  3172.           
  3173.      #E   This register will contain the error codes returned from file
  3174.           operations, that is, the direct codes returned by the operating system
  3175.           instead of the Q-PRO 4 high level codes.  For example, end of media
  3176.           would be returned to #E. The possible contents of this register are
  3177.           listed in the computers system manual.  This is a read only register.
  3178.      #F   The current field on the screen that the cursor is in.  Fields are
  3179.           numbered starting with zero from top to bottom, and moving from left
  3180.           to right.  Its number will be the same as the offset in the format
  3181.           file listing.  This is a read only register.
  3182.  
  3183.      #K   The key-out register.  A read only register that contains the numeric
  3184.           code describing how the operator exited the last field (causing the
  3185.           current proc to be executed).  Values for #K are:
  3186.  
  3187.                 1 - tabbed out
  3188.                 2 - backtabbed out
  3189.                 3 - cursor up
  3190.                 4 - cursor down, newline
  3191.                 5 - cursor left
  3192.                 6 - cursor right
  3193.                 7 - enter
  3194.                 8 - home
  3195.                 9 - any function key
  3196.                10 - break
  3197.  
  3198.      #L   The line counter.  Incremented each time a WRITE 0 is issued. It is
  3199.           reset to 0 when the command RESTART 0 is issued.
  3200.  
  3201.      #P   The page counter.  Incremented each time a RESTART 0 is issued.
  3202.  
  3203.  
  3204.                                         Tables
  3205.                                         ------
  3206.  
  3207.      One of the most powerful features of Q-PRO 4 is the use of tables.  These
  3208.      tables may be used simply to validate data or, in a more sophisticated way,
  3209.      they may be used to dynamically load registers for complex data handling. 
  3210.      The form of the table search verb, TSEAR, is:
  3211.  
  3212.      TSEAR <table name> AT <data item 1>{,<data item 2>, <data item 3>,. .
  3213.      .}{:error}
  3214.      Where:
  3215.  
  3216.      table name     A table in the program which was declared by the statement 
  3217.  
  3218.      AT             Where to look for a match
  3219.  
  3220.  
  3221.  
  3222.                                        Tutorial
  3223.                                           40
  3224.  
  3225.  
  3226.  
  3227.  
  3228.  
  3229.  
  3230.  
  3231.      data item 1    Where to put the second element of the line in the table
  3232.  
  3233.      data item 2    Where to put the third element of the line in the table
  3234.  
  3235.      {:error}       Branch to this label if there is no match
  3236.  
  3237.      Example:
  3238.  
  3239.      TSEAR  EXTABLE AT #N1,#S1,#N2,#N3:10010
  3240.  
  3241.      In this example, the table looks like this
  3242.  
  3243.      TABLE EXTABLE
  3244.  
  3245.      1, "CUSTNAME",      15,  12
  3246.      2, "STATE",         2,   10
  3247.      3, "ZIP",           5,   10
  3248.      END
  3249.          
  3250.  
  3251.      The command TSEAR will look in numeric register one (#N1) for a match with
  3252.      the first column of the table, 1, 2, or 3.  If a match is made, it will
  3253.      take the second element of the row in which a match was made and place it
  3254.      in string register one (#S1), and the third element in numeric register two
  3255.      (#N2).  The fourth element will go into numeric register three (#N3).
  3256.  
  3257.      If #N1 contains a 1, then this command loads #S1 with CUSTNAME, #N2 with
  3258.      15, and #N3 with 12.
  3259.  
  3260.      If #N1 contains neither 1, 2, or 3, the error branch will be taken.
  3261.  
  3262.      Loading a Table with External Data
  3263.      ----------------------------------
  3264.      The elements of a table are not limited to the literals that were shown
  3265.      above.  A table element can be any appropriate data item such as a file
  3266.      data field, register, etc.  Examples of such use are for payroll tax
  3267.      tables, due dates, etc. 
  3268.  
  3269.      To illustrate this use, let us look at a payroll tax table.  We will to
  3270.      load a memory array from a file array with the state names which will be
  3271.      the arguments of the table.  Then we will load the state tax tables into a
  3272.      memory array and thence to the elements of a table.
  3273.  
  3274.      In this case, there are three state tax tables to be loaded from three
  3275.      records on the file.  Each record has the following data layout:
  3276.  
  3277.      RECORD FIELD      CONTENTS   
  3278.  
  3279.           STATE          State Name
  3280.  
  3281.  
  3282.                                        Tutorial
  3283.                                           41
  3284.  
  3285.  
  3286.  
  3287.  
  3288.  
  3289.  
  3290.  
  3291.  
  3292.           TAX(0)         First element of tax table
  3293.           TAX(1)         Second element of tax table
  3294.           TAX(2)         Third element of tax table
  3295.           TAX(3)         Fourth element of tax table
  3296.  
  3297.      There are two memory arrays, STATE with three elements, and TAX with 12
  3298.      elements.  Below is the code to read the file, load the memory arrays and
  3299.      load the table. 
  3300.  
  3301.      PROC LOAD
  3302.      * Define arrays, open file and load arrays.
  3303.  
  3304.           VRBL STATE, X,2,3
  3305.      * STATE is now defined as a string, two characters, and three elements.
  3306.  
  3307.           VRBL TAX, N,6,4
  3308.      * TAX is now defined as numeric, 6 characters, and four elements.
  3309.  
  3310.           OPEN "TAXFILE.DAT" USING "TAXFILE.FID",1:100
  3311.      FOR #N1 EQ 0 TO 2
  3312.           READ 1:END_FILE     
  3313.           MOVE &STATE[1,#N1] TO STATE[#N1]
  3314.           FOR #N2 = 0 TO 3
  3315.                MOVE &TAX[1,#N2] TO TAX[#N2 +(#N1 * 4)]
  3316.           ENDFOR #N2
  3317.      ENDFOR #N1
  3318.           END
  3319.  
  3320.      TABLE TAX_TABLE
  3321.           STATE[0],      TAX[0], TAX[1], TAX[2], TAX[3]
  3322.           STATE[1],      TAX[4], TAX[5], TAX[6], TAX[7]
  3323.           STATE[2],      TAX[8], TAX[9], TAX[10], TAX[11]
  3324.           END
  3325.  
  3326.      To calculate the taxes for a state use TSEAR to get the proper state from
  3327.      the screen (a field named ST) and load numeric registers to calculate as
  3328.      shown below:
  3329.  
  3330.      TSEAR TAX_TABLE AT ST, #N1, #N2, #N3, #N4:NO_STATE
  3331.      END
  3332.  
  3333.      Notes on Tables
  3334.      1.  You must insure that elements match.  That is if the argument is a
  3335.      number, then you must match it with a number.  Similarly, if the result is
  3336.      a string, put it into a string data item.
  3337.  
  3338.      2.   If you are dealing with a string argument, remember that spaces are
  3339.      valid parts of a string.  To strip a string of trailing spaces use this
  3340.  
  3341.  
  3342.                                        Tutorial
  3343.                                           42
  3344.  
  3345.  
  3346.  
  3347.  
  3348.  
  3349.  
  3350.  
  3351.      code:
  3352.  
  3353.           MOVE STRING TO #S0 TRIMMED
  3354.  
  3355.      #S0 will contain the data from STRING with trailing spaces cut off.
  3356.  
  3357.  
  3358.  
  3359.                                       Variables
  3360.                                       ---------
  3361.  
  3362.      Introduction
  3363.      ------------
  3364.      One of the neat things about being in data processing is the esoteric
  3365.      vocabulary that we have to confound and confuse the uninitiated.  One of
  3366.      these terms is "variables".  It is undoubtedly one of the words that we
  3367.      love the most because of the confusion we can sow.
  3368.  
  3369.      Definition
  3370.      ----------
  3371.      Let's define the word and remove the confusion.  The word variable comes
  3372.      from the Latin various, meaning changing.   Of the many definitions
  3373.      available in the dictionary, the closest to the data processing meaning is
  3374.      that of the variable in mathematics, something which has no fixed value as
  3375.      opposed to a constant value.
  3376.  
  3377.      However, in data processing, with our talent for jargon, we use variable as
  3378.      a blanket term for a place in the computer memory where some data is stored
  3379.      that we will change periodically.  Accordingly, when we refer to a
  3380.      variable, we are really talking about the contents of some location in
  3381.      memory.  
  3382.  
  3383.      Usage
  3384.      -----
  3385.      Variables are convenient places to stash and retrieve data whose values may
  3386.      change from time to time.  Once a variable is given a name, the value it
  3387.      contains may be used by simply using its name.  The value of a variable is
  3388.      always its most recent.  In other words, whatever was most recently put
  3389.      into the variable is what is there now.  Previous values are discarded.
  3390.  
  3391.      In Q-PRO 4, variables are exactly like screen data fields except that they
  3392.      do not display.  In a more complex form they can be dimensioned.  (Refer to
  3393.      Dimensioned Variables.)
  3394.  
  3395.      For example, data that is on a file may be read in and stored in variables
  3396.      for processing.  After and/or during processing, the variables may be
  3397.      changed to reflect the results of the processing.
  3398.  
  3399.      Other uses of variables include tables of data, or buckets to store values
  3400.  
  3401.  
  3402.                                        Tutorial
  3403.                                           43
  3404.  
  3405.  
  3406.  
  3407.  
  3408.  
  3409.  
  3410.  
  3411.      temporarily.  They may be used in place of a literal number or string in
  3412.      any command.
  3413.  
  3414.      Variable Types
  3415.      --------------
  3416.      In Q-PRO 4, there are numeric and string. Numeric variables may only be
  3417.      used to store numbers and their associated decimal points and signs. 
  3418.      String variables may be used to store any data.
  3419.  
  3420.      When variables are defined to the computer ("declared"), their initial
  3421.      values are set as follows:
  3422.  
  3423.        o  String Variables--all positions are set to blanks
  3424.        o  Numeric Variables--all positions are set to 0
  3425.  
  3426.      Rules
  3427.      -----
  3428.      1.   Variables must be declared before use.
  3429.      2.   A variable name may be up to 10 characters long and the first
  3430.           character must be alphabetic.  This name must NOT be in use by another
  3431.           variable or screen data field.  
  3432.      3.   Variables may be defined as up to 255 characters long.
  3433.      4.   Variables may be dimensioned for up to 65,535 elements--memory
  3434.           permitting.  (Refer to the section on dimensions and handling
  3435.           variables that follows).
  3436.      5.   String variables may be moved to numeric variables or registers if the
  3437.           data moved is numeric.
  3438.      6.   Numeric variables may be freely moved to string variables, fields or
  3439.           registers.
  3440.      7.   Don't put nulls in variables.
  3441.  
  3442.      Declaring Variables
  3443.      -------------------
  3444.      Variables must be "declared",  or explained to the program so that the
  3445.      program knows about them.  They must be declared before they are used.  
  3446.      The most convenient place to declare variables is in procedure LOAD,
  3447.      because procedure LOAD is executed only once by Q-PRO 4 when the program is
  3448.      first loaded into memory.
  3449.  
  3450.      VRBL <variable name>, <type>,  <length> {, <dimension>}
  3451.  
  3452.      Where:
  3453.  
  3454.      VRBL           The command that declares a variable
  3455.  
  3456.      variable name  Up to 10 characters beginning with an alphabetic character
  3457.                     and not in use by another variable or a screen field type.
  3458.       
  3459.      type           X for alphanumeric string or N for numeric.
  3460.  
  3461.  
  3462.                                        Tutorial
  3463.                                           44
  3464.  
  3465.  
  3466.  
  3467.  
  3468.  
  3469.  
  3470.  
  3471.  
  3472.      length         Length in characters
  3473.  
  3474.      dimension      Number of elements reserved for this variable.
  3475.  
  3476.  
  3477.      EXAMPLES:
  3478.  
  3479.      VRBL CUSTNAME, X, 20
  3480.           A variable named CUSTNAME.  It is a string variable.  It has 20
  3481.           character spaces reserved for it.
  3482.      VRBL CUSTNUM, N, 5
  3483.           A variable named CUSTNUM.  It is a numeric variable.  It has 5
  3484.           character spaces reserved for it.
  3485.  
  3486.      Dimensioned Variables
  3487.      ---------------------
  3488.      Dimensioned variables are one of the most convenient and powerful of all
  3489.      facilities in data processing, yet quite confusing.  A dimensioned variable
  3490.      has only one name but many locations for different values.  One way to
  3491.      think of a dimensioned variable is to picture a group of people standing in
  3492.      a row.  Each one is standing in a box.  The first box is labeled PEOPLE0,
  3493.      the second box is labeled PEOPLE1, the third, PEOPLE2, etc.
  3494.  
  3495.      If we move PEOPLE6 to PEOPLE2, we clone the person in the box labeled
  3496.      PEOPLE6 to the box labeled PEOPLE2.  The poor soul in PEOPLE2 disappears in
  3497.      an explosion of bits and bytes, but the person that was in PEOPLE6 is still
  3498.      there as well as being in PEOPLE2.  To further confuse, the dimensioned
  3499.      variable PEOPLE is called an array.
  3500.  
  3501.      Rules for Dimensioned Variables
  3502.      -------------------------------
  3503.      1.   The maximum dimension is 65K.
  3504.      2.   The address of the variable, or the index, starts at zero (0) and goes
  3505.           up to the dimension of the variable less 1.
  3506.  
  3507.      Example - Dimensioned Variables
  3508.           Assume a one dimensioned variable called PEOPLE with ten boxes, each
  3509.           box is technically called an element, which are:
  3510.  
  3511.      Element (Box)Number           Contents
  3512.           0                        JEFF
  3513.           1                        BOB
  3514.           2                        ANDY
  3515.           3                        MIKE 
  3516.           4                        JOSH
  3517.           5                        SUZANNE
  3518.           6                        SARAH
  3519.           7                        LIZ  
  3520.  
  3521.  
  3522.                                        Tutorial
  3523.                                           45
  3524.  
  3525.  
  3526.  
  3527.  
  3528.  
  3529.  
  3530.  
  3531.           8                        MARY 
  3532.           9                        IRENE
  3533.  
  3534.  
  3535.      We would have declared this variable as:
  3536.  
  3537.      VRBL PEOPLE,X,7,10
  3538.           When we refer to PEOPLE[4] we are referring to the contents of the
  3539.           element number 4 which is JOSH.  When we refer to PEOPLE[3] in our
  3540.           program, we are referring to MIKE.  We use this knowledge in such
  3541.           statements as:
  3542.  
  3543.           MOVE PEOPLE[7] TO NAMEFIELD
  3544.       
  3545.           This moves LIZ to a screen data field named NAMEFIELD.
  3546.  
  3547.  
  3548.                                   LANs and Multiuser
  3549.                                   ==================
  3550.  
  3551.  
  3552.      Commands
  3553.      --------
  3554.      From the programmer's viewpoint, all LANs and multiuser systems look the
  3555.      same.  That is, the commands to lock files and lock/unlock records are the
  3556.      same.  To make life less complicated, the multiuser commands are ignored by
  3557.      the single user interpreter.
  3558.  
  3559.      HOST Command
  3560.      ------------
  3561.      The HOST command tells the interpreter what operating system it is running
  3562.      under.  This is the only command that must be changed when you move your
  3563.      programs from system to system.  You can change this command dynamically
  3564.      with an application control file (see following section).  This design
  3565.      makes Q-PRO 4 exceptionally portable.
  3566.  
  3567.      The HOST command must be given before any files are opened or created. 
  3568.      Available HOSTs are:
  3569.  
  3570.      "SINGLE"       Single user
  3571.      "IBMNET"       Netbios compatible, e.g. IBM PC Network, 3+
  3572.      "MSNET"        The same as IBMNET
  3573.      "NETWARE"      Novell NetWare or compatible
  3574.  
  3575.      Record Locking
  3576.      --------------
  3577.      Records are locked with the RLOCK command.  The record that is locked is
  3578.      the one that is currently being pointed to.  This means that an RLOCK
  3579.      command given after a READ will lock the next logical record, not the one
  3580.  
  3581.  
  3582.                                        Tutorial
  3583.                                           46
  3584.  
  3585.  
  3586.  
  3587.  
  3588.  
  3589.  
  3590.  
  3591.      just read.  Thus, the RLOCK command should follow a POSN or a READ NOADV.
  3592.  
  3593.      The record is not physically locked.  The programmer always has access to
  3594.      records under his/her/its control.  Instead of physically locking, Q-PRO 4
  3595.      remembers that another process has asked for a lock on the record and goes
  3596.      on the error path if the program asks to lock the same record.
  3597.  
  3598.      Record Unlocking
  3599.      ----------------
  3600.      The currently locked record is unlocked with the RUNLOCK command.
  3601.  
  3602.      File Locking
  3603.      ------------
  3604.      If the keyword UNLOCKED is not included when files are opened or created,
  3605.      they will be opened or created locked.  Another user trying to open the
  3606.      file will get a message from the system that the file is not available.
  3607.  
  3608.      Program Changes - Single to LAN/Multi
  3609.      -------------------------------------
  3610.      The changes to make your program multiuser are shown below:
  3611.  
  3612.      Example, Multiuser PROC LOAD
  3613.  
  3614.      PROC LOAD
  3615.           HOST "NETWARE"
  3616.           OPEN "CUST.DAT" USING "CUST.FID", 1 UNLOCKED :NO_F
  3617.           GOTO E1
  3618.      NO_F
  3619.           MAKE "CUST.DAT" USING "CUST.FID",1:BAD
  3620.           GOTO E1
  3621.      :BAD ERROR "UNABLE TO CREATE FILE"
  3622.                SYSTEM
  3623.      :E1       END  
  3624.  
  3625.      Multiuser PROC NAMEP
  3626.  
  3627.      PROC NAMEP
  3628.           POSN 1 TO NAME
  3629.           RLOCK  1:USED1
  3630.                Lock the record currently in the buffer.  If it already has a
  3631.                lock on it, goto USED.
  3632.           READ 1:NO_MATCH
  3633.           COPY 1 TO *
  3634.           NEXT
  3635.      :NO_MATCH END
  3636.  
  3637.      USED   ERROR "This record is not available-select another"
  3638.           END
  3639.  
  3640.  
  3641.  
  3642.                                        Tutorial
  3643.                                           47
  3644.  
  3645.  
  3646.  
  3647.  
  3648.  
  3649.  
  3650.  
  3651.      Multiuser Function Keys
  3652.  
  3653.      PROC READ_LOCK
  3654.           Since everybody wants to do this, we will write a subroutine they can
  3655.           all use.
  3656.           READ 1 NOADV:EF
  3657.                Read the record but don't advance, preparatory to trying to lock
  3658.                it.
  3659.           RLOCK 1:USED
  3660.                Lock the record in the buffer.  If it is already locked, goto
  3661.                USED.
  3662.           COPY 1 TO *
  3663.           RETURN
  3664.                Go back to the calling program at the next sequential command.
  3665.      :EF  ERROR "No more records "
  3666.           END
  3667.      PROC KEY1
  3668.                CALL READ_LOCK
  3669.                END
  3670.      PROC KEY2
  3671.           BACKSPACE 1:EF
  3672.                Since we are using NOADV, we need only BACKSPACE once.
  3673.           CALL READ_LOCK  
  3674.           END
  3675.  
  3676.      PROC KEY11
  3677.                POSN 1 TO NAME USING 1
  3678.                CALL READ_LOCK
  3679.                FREE 1
  3680.                END
  3681.  
  3682.      PROC KEY3
  3683.           POSN 1 TO NAME RELATIVE
  3684.           RLOCK  1:USED
  3685.           READ 1:EF
  3686.           COPY 1 TO *
  3687.           END
  3688.  
  3689.      Accession Number Management
  3690.      ---------------------------
  3691.      One of the better methods of transaction number management stores and
  3692.      maintains all the application system access numbers in a single application
  3693.      control file.  Usually, the file is a one record random file that is
  3694.      quickly accessible and updatable.  It contains such accession numbers as
  3695.      next available customer number, next available order number, next available
  3696.      invoice number, etc.  The trick of managing the accession numbers is the
  3697.      timing of when the number is updated.  For example, the customer number is
  3698.      updated when a new customer record is written.  If it is updated at any
  3699.      other time, numbers may be used and never assigned.
  3700.  
  3701.  
  3702.                                        Tutorial
  3703.                                           48
  3704.  
  3705.  
  3706.  
  3707.  
  3708.  
  3709.  
  3710.  
  3711.  
  3712.      Another technique is maintaining them in a record in the working indexed
  3713.      file with a unique and particular key that the programmer knows is for the
  3714.      accession number file.  For example, a file with the key $$***$$ is
  3715.      unlikely to ever be reached by the user.  This is a good method for small
  3716.      applications.  It is a problem for applications with many users because of
  3717.      the large amount of file crunching always going on.
  3718.  
  3719.      The least desirable method, we look at the last record written and add one
  3720.      to its accession number.  This method is not suitable for LANs and
  3721.      multiuser applications.
  3722.  
  3723.                             Restructuring an Indexed File
  3724.                             -----------------------------
  3725.      Adding Keys
  3726.      -----------
  3727.      You cannot change the structure of a data file by simply changing the
  3728.      associated FID file.  While the FID file knows about the change, no one has
  3729.      told the data file.  It takes a small Q-PRO 4 program to do this.
  3730.  
  3731.      The process is very simple, we make a new FID file with the structure we
  3732.      want.  Then we create a new data file with the new FID and copy each old
  3733.      record, one by one to the new file.
  3734.  
  3735.      New FID File
  3736.           Copy the old FID file, OLD.FID to a new file, NEW.FID.  Load Binary
  3737.           WorkStation.  Select the FID generator mode and load NEW.FID.
  3738.       
  3739.           Press F5 to insert a field.  Enter a new field, CUSTNO, that is 10
  3740.           characters long and numeric.
  3741.  
  3742.           Press F4 to update the FID.  Press Shift F10 to return to the editor.
  3743.  
  3744.      The program
  3745.  
  3746.      PROC RESTRUC
  3747.           OPEN "OLD.DAT" USING "OLD.FID",1:100
  3748.           MAKE "NEW.DAT" USING "NEW.FID",2:200
  3749.  
  3750.      :L   READ 1:EOF
  3751.           COPY 1 TO 2
  3752.           GOTO L
  3753.  
  3754.      :EOF CLOSE
  3755.           FCOPY "NEW.DAT", "OLD.DAT"
  3756.           FCOPY "NEW.IDX", "OLD.IDX"
  3757.           ERASE "NEW.DAT"
  3758.           ERASE "NEW.IDX"
  3759.           END
  3760.  
  3761.  
  3762.                                        Tutorial
  3763.                                           49
  3764.  
  3765.  
  3766.  
  3767.  
  3768.  
  3769.  
  3770.  
  3771.  
  3772.                P R O G R A M M E R'S    R E F E R E N C E   M A N U A L
  3773.                ========================================================
  3774.  
  3775.  
  3776.      Naming Conventions
  3777.      -------------------
  3778.      All Q-PRO 4 names follow the conventions shown below.  These conventions
  3779.      apply to screen field names, file field names, variables, and labels.
  3780.  
  3781.       1.  The first character of any name must be an alphabetic character.  The
  3782.           balance may be either alpha or numeric.
  3783.  
  3784.       2.  The name may be up to 10 characters long.
  3785.  
  3786.       3.  Underline characters (_) may be embedded in the name for clarity and
  3787.           they are counted in the 10 character length.
  3788.  
  3789.      Examples:
  3790.  
  3791.      FIELD_NAME          CUST_FILE           NEW_CUS_NA
  3792.  
  3793.  
  3794.      Keyboard
  3795.      --------
  3796.      Q-PRO 4 uses many of the functions of the keyboard as configured to the
  3797.      particular computer and operating system.  For example, in this manual we
  3798.      frequently refer to the "ENTER" key.  This key is different on various
  3799.      computers.  For the IBM PC, it is standardly the END key.  With the
  3800.      configuration utility, SETUP, you may change these keys to meet your own
  3801.      requirements. 
  3802.  
  3803.      Format Files
  3804.      ------------
  3805.      The format, command, or program file is the primary component of a Q-PRO 4
  3806.      application program.  It is created by the programmer.  This file contains
  3807.      the invariant (background) information, field definitions, and programming
  3808.      statements necessary for a Q-PRO 4 application.  The format is created with
  3809.      Binary WorkStation (BW), and executed by the runtime interpreter (QNE).
  3810.  
  3811.      Building a Format
  3812.      -----------------
  3813.      Binary WorkStation is used for writing the programs.  It is entered by
  3814.      typing BW when at the system prompt.  From BW, the user may select an
  3815.      existing file to edit or create a new one.
  3816.  
  3817.      Press return to begin editing. The bottom line of the screen shows the
  3818.      functions available.  Pressing F10 or F9 will scroll the function
  3819.      selections. For more details on the BW editor, see the Binary WorkStation
  3820.  
  3821.  
  3822.                             Programmer's Reference Manual
  3823.                                        Page 50
  3824.  
  3825.  
  3826.  
  3827.  
  3828.  
  3829.  
  3830.  
  3831.      section.
  3832.  
  3833.      Build Screens
  3834.      -------------
  3835.      Select F8 Screen to edit of the background (unalterable) portion of the
  3836.      screen.  To create the background, place the cursor at the location on the
  3837.      screen where you want the background text and type the desired text.  All
  3838.      the cursor control keys, the INSERT/DELETE character and line keys, and the
  3839.      TAB key are active and usable for creating and editing the background.
  3840.  
  3841.      Screen Data Field Definition
  3842.      ----------------------------
  3843.      Place the cursor where you want an entry field and press F1.  The screen
  3844.      definition window will display.  When the field definition process is
  3845.      complete for a field, press RETURN.  Previously defined screen data fields
  3846.      which are denoted by strings of the pound-sign character (#) on the screen. 
  3847.      Although, we call these scream data fields, as you will see later, they may
  3848.      or may not be enterable by the operator.
  3849.  
  3850.      These are the items that are entered to define a screen data field:
  3851.  
  3852.      Field No.      This is the OFFSET of the field as determined by Q-PRO 4. 
  3853.                     It is the sequential number of the field counting from top
  3854.                     to bottom, left to right.  The offset is a most convenient
  3855.                     method of managing screen fields.
  3856.  
  3857.      Field name     The content of this field is a name of up to 10 alphanumeric
  3858.                     characters which follow the Q-PRO 4 naming conventions.  The
  3859.                     name must be unique on the current screen but may be reused
  3860.                     on other screens.  This name may be used as a variable by
  3861.                     the application program.  The name need not correspond to
  3862.                     anything, although some correspondence is useful for
  3863.                     clarity.
  3864.  
  3865.                     To delete a pre-existing field, clear this name area (using
  3866.                     the CLEAR SCREEN key), and then press ENTER.
  3867.  
  3868.      Len            defines the number of character positions to be occupied by
  3869.                     the field on the screen.  A length of 0 is invalid.  If you
  3870.                     use care, fields may be overlapped for special applications. 
  3871.                     However, be cautious, as confusion at data entry time may
  3872.                     occur.
  3873.  
  3874.      Row            The row number occupied by the screen data field.  (Zero is
  3875.                     the topmost row.)  This field is calculated automatically by
  3876.                     FB.  Normally you should skip this field by pressing TAB. 
  3877.                     However, you may relocate the field to a different row of
  3878.                     the screen by altering the value that Q-PRO has already put
  3879.                     in. 
  3880.  
  3881.  
  3882.                             Programmer's Reference Manual
  3883.                                        Page 51
  3884.  
  3885.  
  3886.  
  3887.  
  3888.  
  3889.  
  3890.  
  3891.  
  3892.      Col            is the starting column number of the screen data field. 
  3893.                     Like the R value, this entry is calculated by BW.  It may be
  3894.                     changed if you desire to change the column location of the
  3895.                     screen data field.  The left-most column is zero.
  3896.  
  3897.      Type           The field type descriptor is two characters.  The first
  3898.                     character describes the field attribute; such as numeric
  3899.                     only, alpha only, etc.  The second character specifies
  3900.                     auto-duplication or an invisible field.
  3901.  
  3902.                   First Character
  3903.                   ---------------
  3904.                     Blank (or x)   Any data is allowed in this field.
  3905.                     X              Any data is allowed, but alphabetic data will
  3906.                                    be forced to upper case.
  3907.                     a              Only alphabetic data is allowed.  (A-Z, a-z)
  3908.                     A              Only alphabetic data is allowed.  When
  3909.                                    entered they will be forced to upper case. 
  3910.                                    (A-Z, a-z)
  3911.                     m              Only alphanumeric data is allowed.  (A-Z,
  3912.                                    a-z, 0- 9)
  3913.                     M              Only alphanumeric data is allowed.  When
  3914.                                    entered, any alphabetic data will be forced
  3915.                                    to upper case.  (A-Z, a-z, 0- 9)
  3916.                     N              Only numeric data, its associated sign and
  3917.                                    decimal point is allowed.  (0-9  + - .)
  3918.                     I              Only numeric data and its associated sign are
  3919.                                    allowed (integers only). (0-9  +  -)
  3920.                     D              Only numbers are allowed.  No signs or
  3921.                                    decimal point are allowed.  (0-9)
  3922.  
  3923.                When data is typed into the field by the operator, each keystroke
  3924.                is validated.  It must be within the requirements specified by
  3925.                the descriptor character for the current entry field.  If it is
  3926.                not, an error message will be displayed on line 24 of the CRT and
  3927.                none of the keys (except ESCAPE) on the keyboard will respond.
  3928.  
  3929.                To clear the message, press ESCAPE which will clear the message
  3930.                and allow resumption of keying.  The previous contents of line 24
  3931.                will be restored.  Note that if a screen presentation is desired
  3932.                in which a single entry area is to contain a mixture of types
  3933.                (i.e., three digits, followed by two alphas), multiple screen
  3934.                data fields may be located alongside each other so that they
  3935.                present the appearance of being one field to the operator.
  3936.  
  3937.             Second Character
  3938.             ----------------
  3939.                Blank               No additional functions will be performed at
  3940.  
  3941.  
  3942.                             Programmer's Reference Manual
  3943.                                        Page 52
  3944.  
  3945.  
  3946.  
  3947.  
  3948.  
  3949.  
  3950.  
  3951.                                    the keystroke level.  The field will be
  3952.                                    cleared when ENTER is pressed.
  3953.                =                   "auto- duplication" field.  This means that
  3954.                                    the field is not automatically cleared when
  3955.                                    ENTER is pressed, and the contents of the
  3956.                                    field will remain after ENTER is pressed.
  3957.  
  3958.                                    When entering data, the operator may
  3959.                                    duplicate the previous value by pressing TAB. 
  3960.                                    Alternatively, new data may be typed in the
  3961.                                    field.  On the first keystroke of the newly
  3962.                                    typed data, all character positions from the
  3963.                                    current cursor position to the end of the
  3964.                                    field are cleared before the new character is
  3965.                                    placed in the field.
  3966.  
  3967.                ?                   The field will not be visible.  This is
  3968.                                    useful for passwords.
  3969.  
  3970.      Just      There are four options for justification of the screen field.  If
  3971.                nothing is specified, then the default is left.  NOTE:  All
  3972.                fields are automatically left justified when data is being
  3973.                entered.  The appropriate re-justification is performed as the
  3974.                operator exits the field.
  3975.  
  3976.                     L    Normally, screen fields are left justified.  If nothing
  3977.                          is entered this will be the case.  However, you may
  3978.                          enter an L if you desire.
  3979.                     R    Right justifies the screen field. 
  3980.                     C    Centers the data in the screen field. 
  3981.                     N    No justification of any kind.
  3982.  
  3983.      Fill Char Use this selection to force the fill of unentered space in the
  3984.                screen field.  Most often this specification is left blank. 
  3985.                However, frequently a zero is used along with right justification
  3986.                to produce a left zero filled screen field.  
  3987.  
  3988.                If a number sign (#) is specified as a fill character, blanks
  3989.                will be displayed on the screen.  However, when the field is
  3990.                programmatically referenced (e.g., written to a file), the
  3991.                leading or trailing spaces, as the case may be, are stripped from
  3992.                the field, leaving a variable length result.  This is useful when
  3993.                building files to interface with other programming systems. 
  3994.                CAUTION:  If you are using indexed or random Q-PRO 4 files, DO
  3995.                NOT use the "#".
  3996.  
  3997.                Almost any fill character is valid.  However, for numeric data to
  3998.                be used in computations, the only valid fill characters are blank
  3999.                (used for left justified numeric data), and 0 (used for right
  4000.  
  4001.  
  4002.                             Programmer's Reference Manual
  4003.                                        Page 53
  4004.  
  4005.  
  4006.  
  4007.  
  4008.  
  4009.  
  4010.  
  4011.                justified data).
  4012.  
  4013.                     The default is a blank.
  4014.  
  4015.      May Ent.  Y    Indicates that the operator may enter data in this field.
  4016.                N    Prevents the operator from entering data in this field. 
  4017.                     This is useful for message fields, total fields, or other
  4018.                     computed or derived data items.
  4019.  
  4020.                     The default value is "Y".
  4021.  
  4022.      Must Ent. Y    Indicates that if the operator reaches this field, then some
  4023.                     data must be entered.
  4024.                N    Indicates that the operator need not enter data here.
  4025.  
  4026.                     The default value is "N".
  4027.  
  4028.      Must Fill Y    Indicates that the operator must enter the field and must
  4029.                     fill the field.
  4030.                N    Indicates that the operator need not fill the field. 
  4031.  
  4032.                     The default is "N".
  4033.  
  4034.      Must Tab  Y    Indicates that the operator must press TAB or some other
  4035.                     cursor control key to exit the field.
  4036.                N    Indicates that the operator will leave the field if TAB is
  4037.                     pressed or the field is filled. 
  4038.  
  4039.                     The default is "N."
  4040.  
  4041.      Procedure
  4042.      name      This entry may contain the name of a procedure in the program
  4043.                code or it may be left blank.  If a procedure is named, the name
  4044.                must follow the Q-PRO 4 naming conventions.  The procedure will
  4045.                be executed each time the operator exits this screen data field. 
  4046.                This procedure may do extended validity checks and calculations,
  4047.                I/O to a file, or anything else you can think of.
  4048.  
  4049.  
  4050.  
  4051.  
  4052.  
  4053.  
  4054.  
  4055.  
  4056.  
  4057.  
  4058.  
  4059.  
  4060.  
  4061.  
  4062.                             Programmer's Reference Manual
  4063.                                        Page 54
  4064.  
  4065.  
  4066.  
  4067.  
  4068.  
  4069.  
  4070.  
  4071.                                 THE PROGRAMMING SYSTEM
  4072.                                 ======================
  4073.  
  4074.      Procedures
  4075.      ----------
  4076.      Q-PRO 4 programs are composed of commands organized into procedures.  Each
  4077.      procedure is executed in at least one of three ways:
  4078.  
  4079.           1.   As a procedure associated with a screen data field.
  4080.           2.   As a standard system procedure.
  4081.           3.   As a procedure called from another procedure.
  4082.  
  4083.      Screen Data Field Procedures
  4084.      ----------------------------
  4085.      The procedure name must conform to the Q-PRO 4 naming conventions
  4086.      previously described.  The sequence in which procedures occur in a Q-PRO 4
  4087.      program is not significant.  Therefore, the programmer is free to define
  4088.      some set of procedure-naming and placement standards that best suits him. 
  4089.      One suggested programming standard is to name field procedures the same as
  4090.      their associated screen data fields, followed with a "P" (i.e., a screen
  4091.      data field named CUSTNO would be linked to a procedure named CUSTNOP).
  4092.  
  4093.      A screen data field procedure is executed when the screen data field is
  4094.      exited by the operator (except for a back tab when no data has been
  4095.      entered).  Procedures normally end by giving control back to the operator
  4096.      and may redirect the cursor to any screen data field.
  4097.      Other types of procedures are discussed later in this chapter.
  4098.  
  4099.      A procedure is defined by a PROC statement, as shown below.  
  4100.  
  4101.      PROC CUSTNOP
  4102.  
  4103.      Within the procedure are (normally) executable statements, of the form
  4104.  
  4105.           {label:} statement  {:error}
  4106.  
  4107.      label     The label portion of the statement is optional.  If present, it
  4108.                follows the standard name conventions.  It optionally may be
  4109.                followed by a colon (:).  The label may be a number or an
  4110.                alphanumeric label.  If it is an alphanumeric label, it must be
  4111.                prefaced by a colon (:).  The label is used for control transfer
  4112.                (GOTO) and error trapping statements.  NO EMBEDDED SPACES ARE
  4113.                ALLOWED.
  4114.  
  4115.      statement The statement is a Q-PRO 4 command or construct.
  4116.  
  4117.      error     The error branch (a label to go to on error) is valid only on
  4118.                certain types of statements.  If given, it must be preceded by a
  4119.                colon.
  4120.  
  4121.  
  4122.                             Programmer's Reference Manual
  4123.                                        Page 55
  4124.  
  4125.  
  4126.  
  4127.  
  4128.  
  4129.  
  4130.  
  4131.      Data Items
  4132.      ----------
  4133.      A programming language is not of much use without data to manipulate.  In
  4134.      this manual, we will refer to the following six types of data items:
  4135.           1.    Data Registers
  4136.           2.    Special Registers
  4137.           3.    Screen data fields
  4138.           4.    Literals
  4139.           5.    Variables
  4140.           6.    File data fields
  4141.  
  4142.  
  4143.      1.   Data Registers
  4144.           --------------
  4145.           There are two types of data registers, string and numeric.  There are
  4146.           10 of each type of register, designated as:
  4147.  
  4148.           #N0-#N9   Numeric registers.  Numeric registers may contain an integer
  4149.                     or real number of up to 20 digits.  This value may be
  4150.                     manipulated, written to a file, examined, or overwritten in
  4151.                     any way. 
  4152.  
  4153.           #S0-#S9   String registers.  String registers may contain a string
  4154.                     (i.e., any data, alphanumeric, numeric, etc.) of up to 255
  4155.                     characters.  These registers may be manipulated, with the
  4156.                     MOVE, INSTR, CONCAT and other commands which provide
  4157.                     mechanisms for extracting substrings, performing
  4158.                     concatenation of strings, etc.  String registers are NEVER
  4159.                     padded with blanks.  They terminate with a null unless the
  4160.                     programmer inserts blanks.
  4161.  
  4162.           Data registers also may be accessed by an indexing expression, which
  4163.           must evaluate to a number between 0 and 9 (i.e., #S[#N0+2]).  (Refer
  4164.           to EXPRESSIONS in this chapter.) 
  4165.  
  4166.      2.  Special Registers
  4167.          -----------------
  4168.           #B0-#B9   The Boolean or flag registers.  They may be SET or RESET,
  4169.                     and are used to mark the occurrence of special events within
  4170.                     an application.
  4171.  
  4172.           #F        A read-only numeric register which contains the current
  4173.                     screen field number (as shown on the format file listing).
  4174.                     Since fields can be referenced indirectly through $FIELD
  4175.                     (see Functions, below), this means that generalized code can
  4176.                     be written to handle several like fields using $FIELD[#F]
  4177.                     instead of the field names themselves.
  4178.  
  4179.  
  4180.  
  4181.  
  4182.                             Programmer's Reference Manual
  4183.                                        Page 56
  4184.  
  4185.  
  4186.  
  4187.  
  4188.  
  4189.  
  4190.  
  4191.           #L        The line counter register.  It is incremented every time a
  4192.                     line is written to the list device with a WRITE 0 statement. 
  4193.                     When a RESTART 0 statement is executed (producing a form
  4194.                     feed on the printer), #L is cleared (or set to an optional
  4195.                     number of line feeds following the form feed).
  4196.  
  4197.           #P        The page number register is incremented every time a RESTART
  4198.                     0 statement is executed.  Refer to the Commands section for
  4199.                     more details on RESTART and WRITE.
  4200.  
  4201.                     To start a report, set both registers to 0, and the normal
  4202.                     course of output to the printer will maintain the registers
  4203.                     after that.  To sense the need for a new page, a line of
  4204.                     code similar to the following should be executed after every
  4205.                     print line: IF #L=PAGELENGTH THEN CALL HEADING
  4206.  
  4207.                     To output the page number to a report, the following
  4208.                     sequence might be used:
  4209.  
  4210.                     RESTART 0
  4211.                     PUT "PAGE " TO 0
  4212.                     PUT #P TO 0
  4213.                     WRITE 0
  4214.  
  4215.                     Of course, using the report generator is even easier.
  4216.  
  4217.           #E        The error register.  The contents of this register are the
  4218.                     error codes as returned from file operations.  These are the
  4219.                     direct codes returned by the operating system instead of the
  4220.                     Q-PRO 4 high level codes.  The possible contents of this
  4221.                     register are listed in the appropriate system manuals as
  4222.                     being returned from a specific system call.
  4223.  
  4224.           #K        The keyout register has a numeric code telling what control
  4225.                     key caused control to be given to the program.  The values
  4226.                     for this register are as follows:
  4227.  
  4228.                     0 - typed out
  4229.                     1 - tabbed out
  4230.                     2 - backtabbed out
  4231.                     3 - cursor up
  4232.                     4 - cursor down, newline
  4233.                     5 - cursor left
  4234.                     6 - cursor right
  4235.                     7 - enter
  4236.                     8 - home
  4237.                     9 - any function key
  4238.                     10 - break
  4239.  
  4240.  
  4241.  
  4242.                             Programmer's Reference Manual
  4243.                                        Page 57
  4244.  
  4245.  
  4246.  
  4247.  
  4248.  
  4249.  
  4250.  
  4251.  
  4252.      3.  Screen Data Fields
  4253.          ------------------
  4254.           Screen data fields are defined by the programmer.  They may be
  4255.           manipulated in any way.  As their value changes, that change is always
  4256.           reflected on the screen.  Fields may be accessed directly by their
  4257.           names or indirectly through the $FIELD function.
  4258.  
  4259.                FOR #N0=0 TO 3
  4260.                     MOVE $FIELD[#N0+1] TO $FIELD[#N0]
  4261.                ENDFOR #N0
  4262.                CLEAR $FIELD[#N0]
  4263.  
  4264.      4. Literals
  4265.         --------
  4266.           Literals (constant values) may be numeric or string or control
  4267.           character.  Literals may be used in any computation or manipulation
  4268.           (including direct output to files), except that they may not be stored
  4269.           into.
  4270.  
  4271.           String Literals     String literals must be delimited with either
  4272.                               single (') or double (") quotes which must be
  4273.                               paired.  Strings may not be delimited by mixed
  4274.                               single and double quotes (i.e., 'THIS IS
  4275.                               ILLEGAL"), although a string delimited by one type
  4276.                               of quote may contain the other type (e.g., 'And I
  4277.                               quote, "Four score and seven"').
  4278.  
  4279.                               String literal examples:
  4280.                               "THIS IS A STRING LITERAL"
  4281.                               'This is a string literal with single quotes'
  4282.  
  4283.           Numeric Literals    Numeric literals are numbers.  They may include
  4284.                               the decimal point (.) and be preceded by a minus
  4285.                               (-) sign.  They may not include any non-numeric
  4286.                               characters such as a comma (,) or a dollar sign
  4287.                               ($).  Numeric literals are not delimited with
  4288.                               quotes.
  4289.  
  4290.  
  4291.                               Numeric literal examples:
  4292.                               19746
  4293.                               289567
  4294.  
  4295.  
  4296.      Control Character Literals    A control character is a decimal literal or
  4297.                                    any numeric data item preceded by an at (@)
  4298.                                    sign.  The binary equivalent of the decimal
  4299.                                    value will be treated as a string literal of
  4300.  
  4301.  
  4302.                             Programmer's Reference Manual
  4303.                                        Page 58
  4304.  
  4305.  
  4306.  
  4307.  
  4308.  
  4309.  
  4310.  
  4311.                                    1 character.  This feature is most frequently
  4312.                                    used for controlling printers with special
  4313.                                    features such as expanded print, vertical
  4314.                                    tabbing, etc., or in sending special control
  4315.                                    commands to the screen.  
  4316.  
  4317.                                    Control character literal examples:
  4318.  
  4319.                                    @44
  4320.                                    @#N0
  4321.  
  4322.                                    To put an OKIDATA into bold print mode, you
  4323.                                    could use this sequence:
  4324.  
  4325.                                    PUT  @29 TO 0
  4326.  
  4327.      5. Variables
  4328.         ---------
  4329.           Variables are data items, maintained in memory, which can be used in
  4330.           computations or to build strings.  They may be accessed in the same
  4331.           manner as screen data fields.  In general they behave in the same
  4332.           manner as screen data fields (i.e., may take on a value, may be
  4333.           extracted from a file, may be incremented or decremented, etc.).
  4334.  
  4335.           Variables are defined by the programmer in VRBL statements, which are
  4336.           normally executed at format load time in PROC LOAD.  They may take on
  4337.           single values (in which case, they are referenced directly by name),
  4338.           or multiple values (in which case, we call them ARRAYS, and reference
  4339.           them by an indexing expression which names the specific element of the
  4340.           array we desire to access).  Variables may be used anywhere or in any
  4341.           expression in place of fields, literals, or registers.  The maximum
  4342.           array size is 65,000 elements (memory permitting).
  4343.  
  4344.      6. File Data Fields
  4345.         ----------------
  4346.           Fields in data records may be accessed in two ways--either by their
  4347.           relative positions within the record, or by their names.  The second
  4348.           way is more to be desired, and is accomplished by associating a FID
  4349.           (field item descriptor) file with a data file at MAKE or OPEN time. 
  4350.           These FID files are nothing more than a list of fields and their
  4351.           locations within a record.  Using this approach, the programmer never
  4352.           has to worry where a field is within a record, even if a record format
  4353.           has changed since it was last used.
  4354.  
  4355.           FID files are built with the FID option of Binary Workstation
  4356.           described in the chapter on BW.  When a data file has been opened
  4357.           using a FID file, then fields within the record may be accessed using
  4358.           the following general syntax:
  4359.  
  4360.  
  4361.  
  4362.                             Programmer's Reference Manual
  4363.                                        Page 59
  4364.  
  4365.  
  4366.  
  4367.  
  4368.  
  4369.  
  4370.  
  4371.            &name[file number{,array element number}]
  4372.  
  4373.           The ampersand (&) in front of the field name tells Q-PRO 4 that this
  4374.           is a file field name.  The  name tells the system where on the record
  4375.           the data is located.  The number tells the system which file is to be
  4376.           used (since different files may have the same field names).  The
  4377.           optional index selects one element from a field array when
  4378.           appropriate.
  4379.  
  4380.           Example:
  4381.  
  4382.           &CUSTNAME[1]   This denotes the field CUSTNAME from file 1.
  4383.  
  4384.  
  4385.                                  Standard Procedures
  4386.                                  -------------------
  4387.  
  4388.      Any procedure may be linked to a screen field by naming that procedure in
  4389.      the field definition phase of the format building process.  There are
  4390.      certain procedures which, although left up to the programmer to define,
  4391.      have special significance to the Q-PRO 4 system.  Not defining these
  4392.      procedures, however, does not necessarily result in an error.  Standard
  4393.      procedures are not usually linked to screen data fields.
  4394.  
  4395.      PROC BREAK
  4396.      ----------
  4397.           Executed when:
  4398.  
  4399.       1.  A BREAK key has been defined (standardly control C) through SETUP,
  4400.           and;
  4401.  
  4402.       2.  Breaks are enabled (default is BRON) with the command BRON, and;   
  4403.  
  4404.       3.  The system is NOT currently accepting input from the operator (e.g. is
  4405.           printing a report, searching a file, etc.), and;
  4406.  
  4407.       4.  The defined BREAK key is pressed.
  4408.  
  4409.           A RETURN from PROC BREAK goes to the statement after the calling
  4410.           statement.  When Q-PRO 4 loads, it initializes as BRON.
  4411.  
  4412.      PROC ENTER
  4413.      ----------
  4414.      Executed when the operator presses the DESIGNATED ENTER (standardly the
  4415.      return key on the IBM PC) key, signifying "data entry complete."  This pro-
  4416.      cedure might be used to update a file record, chain to another format, etc. 
  4417.      It also clears all operator enterable screen data fields.
  4418.  
  4419.      PROC ERROR
  4420.  
  4421.  
  4422.                             Programmer's Reference Manual
  4423.                                        Page 60
  4424.  
  4425.  
  4426.  
  4427.  
  4428.  
  4429.  
  4430.  
  4431.      ----------
  4432.      Used as the first level of error trapping provided to the programmer.  For
  4433.      a full discussion of errors and error handling, refer to Chapter 4.
  4434.  
  4435.      PROC KEY0-20
  4436.      ------------
  4437.      Used to link application code to function key sequences.  That is, pressing
  4438.      function key 0 (ESC on the IBM PC) causes PROC KEY0 to be executed
  4439.      immediately if in field entry mode and not executing (printing, search,
  4440.      etc.); pressing function key 1 causes procedure KEY1 to be executed
  4441.      immediately, etc.  If a procedure is not declared for a function key
  4442.      (except key 0), and that key is pressed, an error message is displayed on
  4443.      the screen.  The error may be recovered from by pressing the ESCAPE key.
  4444.  
  4445.      If procedure KEY0 is not defined and ESC is pressed, Q-PRO 4 will execute a
  4446.      SYSTEM command, which closes any open files and returns to the system. 
  4447.      This is the only function key with a "default value."
  4448.  
  4449.      PROC LOAD
  4450.      ---------
  4451.      Automatically executed the first time a format is loaded into memory.  It
  4452.      is typically used to open data files, set initial register contents, etc.
  4453.  
  4454.  
  4455.                                    Statement Types
  4456.                                    ---------------
  4457.  
  4458.      There is a wide variety of statement types in Q-PRO 4. Some, such as those
  4459.      that deal with file handling and error trapping, are dealt with in their
  4460.      own respective chapters.  All are fully defined in the System Commands
  4461.      chapter.  The following is a list of the various statement types, and the
  4462.      statements which fall into each category:
  4463.  
  4464.      File Handling
  4465.      -------------
  4466.      ERASE, OPEN, MAKE, CLOSE, PUT, GET, READ, WRITE, COPY, FREE, RESTART, POSN,
  4467.      SECURE, BACKSPACE, FILETYPE, RENAME, FSEAR, FCBADDR, KEY, FCOPY, RCLEAR
  4468.  
  4469.      Error Handling
  4470.      --------------
  4471.      ERRTRAP, ERROR, NCHECK
  4472.  
  4473.      Arithmetic
  4474.      ----------
  4475.      ADD, SUB, MUL, DIV, ROUND, CALC,  ^, MATHLIB, NOMATHLIB
  4476.  
  4477.      Logical
  4478.      -------
  4479.      SET, RESET
  4480.  
  4481.  
  4482.                             Programmer's Reference Manual
  4483.                                        Page 61
  4484.  
  4485.  
  4486.  
  4487.  
  4488.  
  4489.  
  4490.  
  4491.  
  4492.  
  4493.  
  4494.      Control Transfer
  4495.      ----------------
  4496.      GOTO, CALL, RETURN, CHAIN, END, FOR, ENDFOR, BRON, BROFF  
  4497.  
  4498.      Conditional
  4499.      -----------
  4500.      IF, ON, BEGIN, ENDBEGIN, WHILE, UNTIL, ELSE
  4501.  
  4502.      Screen Control
  4503.      --------------
  4504.      CLEAR, HOME, HOMECLEAR, NEXT, RESUME, LOCK, UNLOCK, BELL, BUFFER, CURSOR,
  4505.      PRINT, HON, HOFF, FILL 
  4506.  
  4507.      Data Formatting
  4508.      ---------------
  4509.      EDIT, UNEDIT, RJUST, LJUST, CENTER, CURRENCY, UCASE, INSTR
  4510.  
  4511.      Data Movement
  4512.      -------------
  4513.      MOVE, CONCAT, ASEAR
  4514.  
  4515.      Table Management
  4516.      ----------------
  4517.      TSEAR
  4518.  
  4519.      Operating System Interface
  4520.      --------------------------
  4521.      RUN, SYSTEM, FORMLOAD, NOFORMLOAD  
  4522.  
  4523.      Debugging
  4524.      ---------
  4525.      TRACE, NOTRACE, DEBUG, FORMLOAD, NOFORMLOAD
  4526.  
  4527.      Machine Language Interface
  4528.      --------------------------
  4529.      MEMEND, LOAD, EXEC, PEEK, POKE, DEFSEG, $MEMEND()
  4530.  
  4531.      Multiuser Management
  4532.      --------------------
  4533.      RLOCK, RUNLOCK, HOST, LPDETACH, LRETRY
  4534.  
  4535.      Miscellaneous
  4536.      * (COMMENT), PRINTSCN, SIZE, HELP, JDPACK, JDUNPACK, SETDATE, GETDATE
  4537.  
  4538.      Functions
  4539.      ---------
  4540.  
  4541.  
  4542.                             Programmer's Reference Manual
  4543.                                        Page 62
  4544.  
  4545.  
  4546.  
  4547.  
  4548.  
  4549.  
  4550.  
  4551.      $ASC(), $ETOX(), $FIELD(), $INT(), $LN(), $MEMEND(), $OFFSET()
  4552.  
  4553.  
  4554.      Expressions
  4555.      -----------
  4556.      Expressions are used by Q-PRO 4 as part of commands as calculations instead
  4557.      of literal numbers.  For example, a particular element in an array which is
  4558.      desired at a given time is 5 or ARRAY[5]; at another time, it may be 6,
  4559.      etc.  This element may be calculated in an expression such that it is
  4560.      dynamically set instead of explicitly set by ARRAY[expression].  The
  4561.      expression is any set of numeric data items such as:
  4562.  
  4563.           ARRAY[#N1+(#N2 * #N3)]
  4564.           ARRAY[ARRAY[#N3]]
  4565.  
  4566.                                     Screen Offset
  4567.                                     -------------
  4568.  
  4569.      The SCREEN OFFSET allows the programmer to address the fields on the screen
  4570.      as offsets from the first variable field.  The first screen data field on
  4571.      the screen, starting from top to bottom, right to left, is numbered zero
  4572.      (0).  The rest follow sequentially.  Thus, the programmer may dynamically
  4573.      select fields on the screen according to the program logic or a table
  4574.      look-up.  Either a literal or an expression may be used to address the
  4575.      field with the function $FIELD [numeric register, literal, or arithmetic
  4576.      expression]. 
  4577.  
  4578.      Example:
  4579.  
  4580.           MOVE $FIELD[5] TO $FIELD[6]
  4581.  
  4582.           Moves the sixth field on the screen, (counting from the top left field
  4583.           on the screen and going from left to right, top to bottom, starting
  4584.           with field zero) to the seventh field.
  4585.  
  4586.           The use of $FIELD allows handling of fields on the screen by position
  4587.           on the screen without worrying about the name of the field.  Thus, the
  4588.           combination of loops, registers and tables gives extraordinary screen
  4589.           handling capability.  #F can be used in this command.
  4590.  
  4591.      Example:  scrolling fields through the screen., using the screen format
  4592.      below:
  4593.  
  4594.           Field 0   ###############   Field 1  ##############
  4595.  
  4596.           Field 2   ###############   Field 3  ##############
  4597.           
  4598.  
  4599.      The program code:
  4600.  
  4601.  
  4602.                             Programmer's Reference Manual
  4603.                                        Page 63
  4604.  
  4605.  
  4606.  
  4607.  
  4608.  
  4609.  
  4610.  
  4611.  
  4612.           FOR #N0 = 0 TO 2
  4613.           * Begins a FOR loop from 0 to 2.
  4614.                MOVE $FIELD[#N0+1] TO $FIELD[#N0]
  4615.           * Moves FIELD 1 (#N0 plus 1) to FIELD 0. 
  4616.           * Then moves FIELD 2 to FIELD 1.  Then moves FIELD 3 to FIELD 2.
  4617.           ENDFOR #N0 
  4618.           END
  4619.           
  4620.           Note that in the contents of the brackets following the $FIELD will be
  4621.           evaluated as an expression.  This expression must evaluate to an
  4622.           integer.  The following are all valid:
  4623.  
  4624.           $FIELD[(#N1 * #N2) + 10]
  4625.           $FIELD[#N1 + #N2 - 20]
  4626.           $FIELD[SCNFIELD + 5]
  4627.           $FIELD[#F]
  4628.  
  4629.                                 Structured Programming
  4630.                                 ----------------------
  4631.       
  4632.      BEGIN and ENDBEGIN
  4633.      ------------------
  4634.      BEGIN denotes the beginning of the structured construct.  BEGINs may be
  4635.      nested and may have any of the following modifiers.
  4636.  
  4637.      BEGIN
  4638.      BEGIN WHILE . . . 
  4639.      BEGIN UNTIL . . . 
  4640.      BEGIN IF . . .
  4641.  
  4642.      ENDBEGIN denotes the end of the structured construct.  It can have any of
  4643.      the following modifiers
  4644.  
  4645.      ENDBEGIN
  4646.      ENDBEGIN WHILE . . .
  4647.      ENDBEGIN UNTIL . . .
  4648.  
  4649.           Examples:
  4650.                BEGIN WHILE A GT 0
  4651.                     SUB &VALUE(100) FROM A
  4652.                     READ 100
  4653.                ENDBEGIN
  4654.  
  4655.                BEGIN UNTIL A EQ 10
  4656.                     ADD 1 TO A
  4657.                ENDBEGIN
  4658.  
  4659.                BEGIN IF A NEQ 0
  4660.  
  4661.  
  4662.                             Programmer's Reference Manual
  4663.                                        Page 64
  4664.  
  4665.  
  4666.  
  4667.  
  4668.  
  4669.  
  4670.  
  4671.                     ADD 1 TO A
  4672.                ENDBEGIN
  4673.  
  4674.                BEGIN
  4675.                     SUB 1 FROM A
  4676.                ENDBEGIN WHILE A LT 100
  4677.  
  4678.      ELSE and ELSE IF
  4679.      ----------------
  4680.      An ELSE or ELSE IF is always associated with a BEGIN IF.  A BEGIN may have
  4681.      any number of IF statements associated with it.  
  4682.  
  4683.      Example:
  4684.           BEGIN IF #N1 GT 100
  4685.                     SUB 1 FROM #N2   
  4686.                ELSE IF #N1 LT 100
  4687.                      ADD 1 TO #N2
  4688.           ENDBEGIN
  4689.  
  4690.  
  4691.                               Tables and Table Handling
  4692.                               -------------------------
  4693.  
  4694.      One unique concept of Q-PRO 4 is that of the table as an addressable
  4695.      entity.
  4696.      A table is a data structure which can be applied to defining default
  4697.      values, verifying keyed-in values, replacing abbreviations with full text,
  4698.      setting up field lengths within records, and many other uses.  It appears
  4699.      as a one or two dimensional matrix, as the following sample table
  4700.      declarations illustrate:
  4701.  
  4702.      TABLE FIRST
  4703.           "ABCD"
  4704.           "DEF"
  4705.            END
  4706.  
  4707.      TABLE SECOND
  4708.           1, "PA"
  4709.           2, "NJ"
  4710.           3, "NY"
  4711.           END
  4712.       
  4713.      A table is conceptually regarded as having some number of rows (the first
  4714.      dimension) and some number of items within each row (the second dimension). 
  4715.      A row may have as few as one item, or as many as will fit on a line. Items
  4716.      MUST be separated by a comma (,).
  4717.  
  4718.      The first element in a table row is called the "key" or "argument" for that
  4719.      row, and is usually a numeric or string literal.  This key is used with the
  4720.  
  4721.  
  4722.                             Programmer's Reference Manual
  4723.                                        Page 65
  4724.  
  4725.  
  4726.  
  4727.  
  4728.  
  4729.  
  4730.  
  4731.      TSEAR statement to locate a particular row within a table. 
  4732.  
  4733.  
  4734.  
  4735.  
  4736.      Table Lookup and Data Verification
  4737.      ----------------------------------
  4738.      Let us suppose that a format screen has a screen data field named STATE,
  4739.      into which the operator will key the usual two-character state
  4740.      identification, but in which we desire to programmatically place the full
  4741.      name of the state, after verifying that the state is one of a valid list of
  4742.      states.  Further suppose that the following table had been declared:
  4743.  
  4744.           TABLE TSTATES
  4745.  
  4746.           "PA",     "PENNSYLVANIA"
  4747.           "DE",     "DELAWARE"
  4748.           "FL",     "FLORIDA"
  4749.           "GA",     "GEORGIA"
  4750.           "NJ",     "NEW JERSEY"
  4751.           "CA",     "CALIFORNIA"
  4752.           END
  4753.  
  4754.      Having this table, we can then verify the entry of a valid state in the
  4755.      field called STATE with the following TSEAR statement:
  4756.  
  4757.           TSEAR TSTATES AT STATE  :100
  4758.  
  4759.      This says the following:
  4760.  
  4761.        o  Within the table called TSTATES, find a row whose key is equal to the
  4762.           current value of the field STATE.
  4763.        o  If a match is found, then go to the next statement.   If no match is
  4764.           found, go label 100. 
  4765.  
  4766.      This use of the TSEAR statement gives us the ability to verify that the
  4767.      state keyed in was one of a valid list of states.
  4768.  
  4769.  
  4770.      Table Lookup, Verification and Replacement
  4771.      ------------------------------------------
  4772.      Going a step further with the example and table above, we can do both the
  4773.      validation and abbreviation replacement with TSEAR as follows:
  4774.  
  4775.       TSEAR TSTATES AT STATE,NSTATE  :100
  4776.  
  4777.      The same search for a match between STATE and a row key within TSTATES will
  4778.      occur.  However, when a match is found, the field NSTATE will take on the
  4779.      value of the next data item in the matched row after the key (here, the
  4780.  
  4781.  
  4782.                             Programmer's Reference Manual
  4783.                                        Page 66
  4784.  
  4785.  
  4786.  
  4787.  
  4788.  
  4789.  
  4790.  
  4791.      full name of the state).  If a whole set of information was tied to a
  4792.      particular state, for example, the beginning and ending ZIP codes, we could
  4793.      put all that data into the table and let TSEAR pull it out when the state
  4794.      is verified.
  4795.  
  4796.  
  4797.      Table Verification and Chaining
  4798.      -------------------------------
  4799.      Another use for tables is the verification of menu selections and
  4800.      subsequent CHAINing to the proper program segment.  For example, suppose we
  4801.      have an application menu as shown below:
  4802.  
  4803.  
  4804.                PAYROLL SYSTEM MENU
  4805.  
  4806.                1- ENTER EMPLOYEE DATA
  4807.  
  4808.                2- ENTER TIME CARDS
  4809.  
  4810.                3- PRINT CHECKS
  4811.  
  4812.                4- PRINT REGISTER
  4813.  
  4814.                5- CHANGE TAX DATA
  4815.  
  4816.                6- EXIT SYSTEM
  4817.  
  4818.                ENTER SELECTION [#]
  4819.  
  4820.      where # denotes a field defined with the name INPUT.  In one statement
  4821.      (using tables), a selection could be automatically verified, and the
  4822.      appropriate program selected for chaining.  The instructions to do this
  4823.      are:
  4824.  
  4825.      PROC ENTER
  4826.      * LOOK UP SELECTION AND GET  THE PROGRAM NAME IF FOUND
  4827.  
  4828.      TSEAR SELECTABLE AT INPUT,#S0  :100
  4829.      * IF PROGRAM NAME IS NULL, THEN WE ARE DONE
  4830.      IF #S0 EQ "" THEN SYSTEM
  4831.  
  4832.      * ELSE LOAD NEW APPLICATION PROGRAM
  4833.      CHAIN #S0
  4834.      100  * THE GIVEN SELECTION IS INVALID
  4835.           ERROR "INVALID CHOICE, PLEASE REENTER"
  4836.           END
  4837.  
  4838.      * THIS IS THE SELECTION TABLE
  4839.  
  4840.  
  4841.  
  4842.                             Programmer's Reference Manual
  4843.                                        Page 67
  4844.  
  4845.  
  4846.  
  4847.  
  4848.  
  4849.  
  4850.  
  4851.           TABLE SELECTABLE
  4852.           1,   "ENTEREMP"
  4853.           2,   "ENTERTC"
  4854.           3,   "PRINTCH"
  4855.           4,   "PRINTREG"
  4856.           5,   "CHANGETAX"
  4857.                END
  4858.  
  4859.      Note that if more selections are added, only the screen and the table need
  4860.      change.  This concept can readily be expanded to include the description
  4861.      line, as well as the file name within the table, so that only the table
  4862.      need be changed as the range of selections expands.
  4863.  
  4864.      Tables as Label Arrays
  4865.      ----------------------
  4866.      An alternative use for tables is as a procedure or label array.  In this
  4867.      use, a table name and index may be used instead of a procedure in a CALL
  4868.      statement, or instead of a label in a GOTO statement.
  4869.  
  4870.      Tables used in this manner are normally not used with the TSEAR command,
  4871.      since lines within the table consist not of keys optionally followed by
  4872.      data, but of single items which are either procedure names (for indexed
  4873.      calls) or labels (for indexed GOTOs).
  4874.  
  4875.      One use of the indexed CALL or GOTO feature might be responding to a menu
  4876.      selection (possibly even using the example above), as follows:
  4877.  
  4878.      PROC ENTER
  4879.      * FIRST VALIDATE THE INPUT
  4880.           IF INPUT = 1 AND INPUT =4 GOTO GOTBL[INPUT1]
  4881.           ERROR "INVALID SELECTION"
  4882.           END
  4883.  
  4884.      * TABLE CONTAINING LIST OF LABELS
  4885.      TABLE GOTBL
  4886.           100
  4887.           200
  4888.           300
  4889.           END
  4890.  
  4891.      Tables as Procedure Arrays
  4892.      --------------------------
  4893.      Another use might be in processing a data file record, whose first field is
  4894.      a record type, as follows:
  4895.  
  4896.      PROC DOREC
  4897.      * RECORD TYPE IS IN &RECTYPE[1]
  4898.           READ 2:EOF
  4899.      * CALL PROCESSOR FOR THIS TYPE
  4900.  
  4901.  
  4902.                             Programmer's Reference Manual
  4903.                                        Page 68
  4904.  
  4905.  
  4906.  
  4907.  
  4908.  
  4909.  
  4910.  
  4911.           CALL PROCTBL[&RECTYPE[1]]
  4912.           RETURN
  4913.           END
  4914.  
  4915.  
  4916.  
  4917.  
  4918.      * TABLE OF ROUTINES FOR DIFFERENT RECORD TYPES
  4919.                TABLE PROCTBL
  4920.                ADDREC
  4921.                DELREC
  4922.                CHANGEREC
  4923.                END
  4924.      Index values for CALL and GOTO tables start with 0 for the first item, 1
  4925.      for the second, etc.
  4926.  
  4927.  
  4928.  
  4929.  
  4930.  
  4931.  
  4932.  
  4933.  
  4934.  
  4935.  
  4936.  
  4937.  
  4938.  
  4939.  
  4940.  
  4941.  
  4942.  
  4943.  
  4944.  
  4945.  
  4946.  
  4947.  
  4948.  
  4949.  
  4950.  
  4951.  
  4952.  
  4953.  
  4954.  
  4955.  
  4956.  
  4957.  
  4958.  
  4959.  
  4960.  
  4961.  
  4962.                             Programmer's Reference Manual
  4963.                                        Page 69
  4964.  
  4965.  
  4966.  
  4967.  
  4968.  
  4969.  
  4970.  
  4971.  
  4972.                                FILES AND FILE HANDLING
  4973.                                =======================
  4974.  
  4975.  
  4976.      File Handler
  4977.      ------------
  4978.      Q-PRO 4, Version 4.0, uses a sophisticated, state-of-the-art B+ tree,
  4979.      multikey file handler.  This file handler is the file BTSYS.EXE, which is
  4980.      terminate and stay resident.  You must load BTSYS or no file handling will
  4981.      occur.  It must be loaded before anything else in the Q-PRO 4 and Q-N-E
  4982.      system.
  4983.  
  4984.      File System Interrupts
  4985.      ----------------------
  4986.      BTSYS uses interrupts 80h, 81h, and 82h.  Other terminate and stay resident
  4987.      programs also grab whatever they want.  As there may be conflict, BTSYS's
  4988.      interrupts are configurable by establishing a DOS system variable, QNEFSI. 
  4989.      For example, to change the interrupts to 8Ah, 8Bh, and 8Ch. before BTSYS is
  4990.      loaded, from AUTOEXEC.BAT or from the command line SET QNESFI = 8A.    
  4991.  
  4992.      Loading BTSYS
  4993.      -------------
  4994.      From the system prompt, type:  BTSYS <cr>
  4995.  
  4996.           or
  4997.  
  4998.           BTSYS QNE  <program name> <cr>
  4999.  
  5000.           (This unloads BTSYS when the program is finished.)
  5001.  
  5002.      From a .BAT file:
  5003.  
  5004.                BTSYS
  5005.  
  5006.                or
  5007.  
  5008.                BTSYS QNE <program name>
  5009.  
  5010.           (This unloads BTSYS when the program is finished.)
  5011.  
  5012.      Unloading BTSYS
  5013.      ---------------
  5014.      From the command line, type:  BTSYS /U <cr>
  5015.  
  5016.  
  5017.  
  5018.  
  5019.  
  5020.  
  5021.  
  5022.                                Files and File Handling
  5023.                                        Page 70
  5024.  
  5025.  
  5026.  
  5027.  
  5028.  
  5029.  
  5030.  
  5031.      File Limitations
  5032.      ----------------
  5033.      Q-PRO 4 has few limitations on files.  These are shown below:
  5034.  
  5035.      Characteristic                          Limit
  5036.        
  5037.       Maximum Field Size                255 characters
  5038.       Maximum Record Size               65K (memory allowing)
  5039.       Maximum File Size                 2 Gbytes
  5040.       Maximum Files Open at One Time    255 (memory allowing)
  5041.       
  5042.  
  5043.      File Types
  5044.      ----------
  5045.      Q-PRO 4 supports four types of files:
  5046.  
  5047.           o random
  5048.           o multi-key index sequential
  5049.           o sequential
  5050.           o sequential with comma delimited fields (SDF files)
  5051.  
  5052.      Common data file handling statements are used for each type of file.  As a
  5053.      programming convenience, access to the system print device is performed
  5054.      with file-like statements. 
  5055.  
  5056.  
  5057.                           Multi-key Indexed Sequential Files
  5058.                           ----------------------------------
  5059.  
  5060.      File Keys
  5061.      ---------
  5062.      Each file may have up to 9 keys or sort sequences. All keys are updated
  5063.      when the record is written.  The primary key may not be duplicated. 
  5064.      Rewriting a record with the same primary key will have the effect of
  5065.      updating the current record; it will NOT create a new record.  You may
  5066.      change keys at any time but you must remember that the file position will
  5067.      not be changed.
  5068.  
  5069.      Records in indexed files are accessed by an alphanumeric key, not by a
  5070.      record number.  The key consists of up to 128 alphanumeric characters.  It
  5071.      may be multi-field and the fields need not be adjacent.      
  5072.  
  5073.      Reading and Writing
  5074.      -------------------
  5075.      Indexed files may be read any key order or in physical order.  When writing
  5076.      a record, the controlling key is the PRIMARY.  In other words, even if you
  5077.      are using a secondary key, the file handler will create the record
  5078.      positioning information correctly.
  5079.  
  5080.  
  5081.  
  5082.                                Files and File Handling
  5083.                                        Page 71
  5084.  
  5085.  
  5086.  
  5087.  
  5088.  
  5089.  
  5090.  
  5091.      When reading an indexed file, it is important to remember that the keys are
  5092.      LEFT JUSTIFIED ASCII CHARACTERS.  In this sense, numbers are considered
  5093.      characters not numbers.  When positioning to a record, the file handler
  5094.      compares the record key and the search key from left to right looking for a
  5095.      match.
  5096.         
  5097.      Physical Order
  5098.      --------------
  5099.      In addition to the 9 keys, the file may be read, positioned, and backspaced
  5100.      in physical order (the order in which it was created) by setting it in key
  5101.      0.  A numeric expression must be used for the record number in the position
  5102.      command.  The BACKSPACE command will back up the file one physical record. 
  5103.  
  5104.      All other commands that affect indexed files will work normally, that is to
  5105.      say, if a record is written, it will be written as an indexed record.
  5106.      If a deleted record is read, then trappable error number 34, Deleted record
  5107.      read.  The record will be loaded into the record buffer. (You can take
  5108.      advantage of this characteristic to recover deleted records.)  
  5109.  
  5110.      Data File
  5111.      ---------
  5112.      An indexed file set consists of two files, the data file which is an ASCII
  5113.      file, and an index file.  Within the file each record is allocated an 8
  5114.      byte internal control field.  If any character, except blank (decimal 32)
  5115.      is in the first 8 bytes, the record is inactive.  Each record is terminated
  5116.      with a carriage return/line feed.  The minimum record length is 10 bytes.
  5117.  
  5118.      Index File
  5119.      ----------
  5120.      There is one index file no matter how many indices are active.  The index
  5121.      file retains all data, even if it is flagged as inactive.  Therefore, the
  5122.      index file may get quite large.  Running the utility QMAINT with the PACK
  5123.      option will compress the index file.    
  5124.      As data records are added to the indexed file, keys are added and the nodes
  5125.      of the index file will split, leaving voids that will be used as the file
  5126.      is updated.
  5127.  
  5128.      The size of the index file is a function of the number of keys, number of
  5129.      records in the data file, and the size of the keys.  The size of the key
  5130.      should be kept as small as possible since the actual key is the secondary
  5131.      key with the primary key appended. 
  5132.  
  5133.      Although a B+ tree index never needs to be balanced, occasionally it should
  5134.      be packed to reclaim disk space.  The state of the index, packed or not,
  5135.      does not materially affect the speed of adding, deleting, or retrieving
  5136.      records.
  5137.  
  5138.      In a single user mode, key nodes are buffered.  Setting BUFFERS = 40 in
  5139.      PC-DOS or MS-DOS is highly recommended.
  5140.  
  5141.  
  5142.                                Files and File Handling
  5143.                                        Page 72
  5144.  
  5145.  
  5146.  
  5147.  
  5148.  
  5149.  
  5150.  
  5151.  
  5152.  
  5153.      Deleted Records
  5154.      ---------------
  5155.      Inactive or deleted records are removed automatically by the file handler
  5156.      if there is frequent corresponding record addition.  The user may remove
  5157.      them with a simple Q-PRO 4 routine to copy the old file with the deleted
  5158.      records to a new file.
  5159.  
  5160.      File Maintenance
  5161.      ----------------
  5162.      The program, QMAINT, has facilities for:
  5163.  
  5164.           o    VERIFYing, or validating, the index file against the data file.
  5165.           o    PACKing, or compressing the index file.
  5166.           o    RECOVERing a damaged index file.  The data file is pure ASCII and
  5167.                can be repaired with any ASCII file handling techniques.  The
  5168.                RECOVER option creates a new index file from the data file.  The
  5169.                implications are, among others:
  5170.  
  5171.                1.   You can delete the index file altogether and still rebuild
  5172.                it.
  5173.  
  5174.                2.   You need only store the data files for backup.
  5175.  
  5176.       
  5177.                                      Random Files
  5178.                                      ------------
  5179.  
  5180.      Structure
  5181.      ---------
  5182.      Random files are identical in structure to indexed files, except there is
  5183.      no index file.  Records may be read or written in order or directly
  5184.      accessed by record number within the file (0 is the record number of the
  5185.      first record). The file's record size may be any length.
  5186.  
  5187.      Maintenance
  5188.      -----------
  5189.      The user is responsible for determining all aspects of a random file's
  5190.      maintenance.  Records are not deleted; the user must keep track of records
  5191.      that he no longer wants to use.
  5192.  
  5193.                                Sequential (text) Files
  5194.                                -----------------------
  5195.  
  5196.  
  5197.      Sequential files are in standard ASCII format, and are compatible with most
  5198.      standard text files (for example, those produced by editors or word
  5199.      processors).  Records in these files may be of varying length.  Records are
  5200.  
  5201.  
  5202.                                Files and File Handling
  5203.                                        Page 73
  5204.  
  5205.  
  5206.  
  5207.  
  5208.  
  5209.  
  5210.  
  5211.      separated with a carriage return/line feed sequence.  Sequential files may
  5212.      be opened only for output, or only for input, and are accessed in
  5213.      sequential record order only.
  5214.  
  5215.                              SDF (Comma Delimited) Files
  5216.                              ---------------------------
  5217.  
  5218.      SDF files are identical to sequential files; except that in an SDF file
  5219.      record, all data fields are delimited by quotes and separated by commas. 
  5220.      Q-PRO 4 will always delimit fields by quotes, but can process records
  5221.      written by other systems which may not put quotes around numeric fields.
  5222.  
  5223.  
  5224.                            Indexed and Random File Handling
  5225.                            --------------------------------
  5226.      Fundamentals
  5227.      ------------
  5228.      All file operations are based on the concept of a file buffer in memory. 
  5229.      The buffer is established with the MAKE or OPEN statement, and removed with
  5230.      the CLOSE statement.  Data coming into or out from a Q-PRO 4 program first
  5231.      passes through a file buffer.
  5232.  
  5233.      A file buffer may be thought of as a string of data.  This string may be
  5234.      accessed in a symbolic, high-level manner (using file field names), or in a
  5235.      specific, low-level manner (using the relative location of data fields
  5236.      within the string).
  5237.  
  5238.      In the course of opening or creating a file, the programmer assigns it a
  5239.      number from 1 to 255.  Thereafter, the file is referenced by its assigned
  5240.      number.
  5241.  
  5242.      Data Dictionary (FID) Files
  5243.      ---------------------------
  5244.      The most convenient method to access fields in a data file record buffer is
  5245.      by name.  To do so, the programmer must first build a FID (file item
  5246.      descriptor, or data dictionary) file using the FID file generator.  The FID
  5247.      file is, in essence, a list of field names and their locations within the
  5248.      record.  To store data in the record, or to extract the data, the
  5249.      programmer need only reference the file data field by name, just like a
  5250.      screen data field, variable, or register.  Not only is this simple to
  5251.      program, but also the program becomes almost completely independent of the
  5252.      record format.  This means that when the record format changes, only the
  5253.      file changes (not the program)!
  5254.  
  5255.      A "data dictionary" facility means that there is a means of documenting
  5256.      file contents and layout.  This is the FID generator which is discussed in
  5257.      detail in its own section.  This high level means of accessing file data is
  5258.      only available for random and indexed files.
  5259.  
  5260.  
  5261.  
  5262.                                Files and File Handling
  5263.                                        Page 74
  5264.  
  5265.  
  5266.  
  5267.  
  5268.  
  5269.  
  5270.  
  5271.      A single data dictionary file may be used for multiple data files. 
  5272.      CAUTION:  Each data file requires its own index file.   Note: A data file
  5273.      must have at 10 characters of data.
  5274.  
  5275.      PC-DOS and MS-DOS File Considerations
  5276.      -------------------------------------
  5277.      For reasons known only to MicroSoft and the mighty blue giant, IBM, their
  5278.      operating systems, MS-DOS and PC-DOS, allow only up to 20 open files
  5279.      (handles) to be used by any one process.  This 20 file limitation is set
  5280.      only if FILES is set to 20 in CONFIG.SYS.  The operating system hogs five
  5281.      handles for itself leaving 15 for the process.  We take one for QNE.EXE
  5282.      which leaves 14 for data files and their associated index files.  Each data
  5283.      file takes one handle and each index takes one handle.
  5284.  
  5285.      Obviously, for useful applications, more than seven indexed data files are
  5286.      a necessity.  So we have found a way to get around the system limits.  As
  5287.      the file system uses files it will eventually run out of file handles.  It
  5288.      will then close the least recently used file that is not locked or has no
  5289.      records locked, and then it will open or reopen the target file.  For
  5290.      example, when you use an eighth data file, the file handler will close one
  5291.      of the other seven data files and open the eighth data file.  If you have
  5292.      many open files in an application, you pay the consequences of the
  5293.      shortsightedness of the masters of software with a lengthened time to open
  5294.      the files when loading the program.  Additionally, there may be a
  5295.      noticeable delay when accessing a file because another file may have to be
  5296.      physically closed and the file being accessed re-opened.  This file
  5297.      handling is transparent to the application designer as the files stay open
  5298.      logically.
  5299.  
  5300.      In the future if the maintainers of DOS, in their wisdom should awaken to
  5301.      the real world, the file system will automatically adjust and open more
  5302.      files before it has go into the virtual file handle mode.
  5303.  
  5304.      File Restructuring
  5305.      ------------------
  5306.      Q-PRO 4 indexed and random files can be restructured, that is new fields
  5307.      added or deleted and/or keys added, changed or removed by writing a simple
  5308.      Q-PRO 4 program.  The principle is to read the old file with its data
  5309.      dictionary and write a new one using the new data dictionary.  The new file
  5310.      will be in the new structure.  The code fragment below illustrates the
  5311.      technique.
  5312.  
  5313.           PROC RESTRUCT
  5314.      * Open the old data file and create a new one to copy to.
  5315.           OPEN "OLD_DAT.DAT" USING "OLD_DAT.FID",1:10
  5316.           MAKE "NEW_DAT.DAT" USING "NEW_DAT.FID",2:20
  5317.  
  5318.      * Read old file and copy/write it to the new until end of file.
  5319.           :L   READ 1:EN
  5320.  
  5321.  
  5322.                                Files and File Handling
  5323.                                        Page 75
  5324.  
  5325.  
  5326.  
  5327.  
  5328.  
  5329.  
  5330.  
  5331.                COPY 1 TO 2
  5332.                WRITE 2:30
  5333.                GOTO L
  5334.           :EN  END
  5335.  
  5336.                                 File Handling Commands
  5337.                                 ----------------------
  5338.  
  5339.      The following paragraphs discuss in detail the Q-PRO 4 statements dealing
  5340.      with file handling.  Each function is further broken down by file type,
  5341.      with an explanation of the implications of each statement for each file
  5342.      type.
  5343.      The full syntax is described in the Q-PRO 4 Commands Chapter.
  5344.  
  5345.      MAKE
  5346.      ----  
  5347.      This statement creates a file (after first deleting it if it already
  5348.      exists) and leaves the file open for later processing.  The syntax of the
  5349.      MAKE statement has four variations, depending on the file type involved.
  5350.  
  5351.      OPEN
  5352.      ----
  5353.      The function of this statement is similar to that of MAKE, except that it
  5354.      refers to a file already in existence on disk.  Therefore, an attempt to
  5355.      open a non-existent file will result in an error.  DO NOT use OPEN to
  5356.      determine if a file is already open, use the FILETYPE command.
  5357.  
  5358.      FILETYPE
  5359.      --------
  5360.      This command has two functions:
  5361.  
  5362.           1.   It returns information about currently open files.
  5363.           2.   It determines if a file is open or closed.
  5364.  
  5365.      CLOSE
  5366.      -----
  5367.      This statement tells Q-PRO 4 that a data file is no longer required for
  5368.      processing.  Although all files will be closed automatically when Q-PRO 4
  5369.      returns to the operating system, good programming practices suggest that
  5370.      files should always be explicitly closed when no longer needed.
  5371.  
  5372.      SECURE
  5373.      ------
  5374.      This command has the same effect on an indexed file as CLOSE, in that it
  5375.      forces the immediate update of internal file information required by Q-PRO
  5376.      4.  However, the file is still left open after the SECURE operation for
  5377.      further processing.  This information is potentially changed after every
  5378.      WRITE or FREE operation.
  5379.  
  5380.  
  5381.  
  5382.                                Files and File Handling
  5383.                                        Page 76
  5384.  
  5385.  
  5386.  
  5387.  
  5388.  
  5389.  
  5390.  
  5391.           Warning:  Turning off the computer without CLOSEing or SECUREing the
  5392.           data files will always corrupt them.  Worse, the operating system will
  5393.           not update the directory and data will be lost.
  5394.  
  5395.  
  5396.  
  5397.      PUT
  5398.      ---
  5399.      PUT is most often used to print directly from Q-PRO 4 and writing
  5400.      sequential and SDF files.  It is not normally used when dealing with files
  5401.      using the FID file option, although it can be.
  5402.  
  5403.      The PUT statement places a data item into a file or printer buffer for
  5404.      later output with the WRITE statement.  (PUT to a sequential file does
  5405.      immediate output.)
  5406.  
  5407.      GET
  5408.      ---
  5409.      GET is not usually used with indexed and random files using FIDs, although
  5410.      it can be.
  5411.  
  5412.      The GET statement retrieves data from a file buffer and stores it into a
  5413.      register or field.  GET is essentially the opposite operation from PUT in
  5414.      this respect.  Be careful when GETting from random or indexed files to
  5415.      avoid overflowing the record buffer.
  5416.  
  5417.      KEY
  5418.      ---
  5419.      The KEY command changes the file key reference of a multikeyed indexed
  5420.      file.  When the file is created or opened, the default file key is one (1). 
  5421.      When the key is changed, all file movements:  POSN, READ, BACKSPACE, etc.
  5422.      will be understood to be in the current key sequence and at the current
  5423.      file position.
  5424.  
  5425.      POSN
  5426.      ----
  5427.      This statement positions the data file to a specific record for reading or
  5428.      writing (random/indexed files only).
  5429.  
  5430.      POSN RELATIVE
  5431.      -------------
  5432.      For indexed files, if the desired key does not exist and the keyword
  5433.      RELATIVE is not given, a READ command to the file will give an end-of-file
  5434.      error.  If the keyword RELATIVE is given, then the file is left positioned
  5435.      at the nearest key higher in value than the key originally specified (if
  5436.      such a key exists).
  5437.  
  5438.      POSN USING
  5439.      ----------
  5440.  
  5441.  
  5442.                                Files and File Handling
  5443.                                        Page 77
  5444.  
  5445.  
  5446.  
  5447.  
  5448.  
  5449.  
  5450.  
  5451.      A variation of the POSN command allows positioning and changing the data
  5452.      file key at the same time.  Obviously, this variant is only used with
  5453.      indexed files.
  5454.  
  5455.  
  5456.  
  5457.      READ
  5458.      ----
  5459.      The READ command loads a data buffer with the currently positioned record
  5460.      (random or indexed files), or advances to the start of the next record
  5461.      (sequential).
  5462.  
  5463.      WRITE
  5464.      -----
  5465.      The WRITE command outputs a data record to a file (random/indexed), or
  5466.      outputs a carriage return/line feed sequence to a file (sequential).
  5467.  
  5468.      RESTART
  5469.      -------
  5470.      This command resets the file buffer pointer to any position within the data
  5471.      buffer (does not apply to sequential files).  This is especially of use in
  5472.      an environment where records are read, displayed, and updated using GETS
  5473.      and PUTS, whether fields occur in sequential order within the record or
  5474.      not.
  5475.  
  5476.      FREE
  5477.      ----
  5478.      The FREE statement marks a record in an indexed file as deleted.  To delete
  5479.      a record, it must be first loaded into the file's data buffer using a READ. 
  5480.      To insure the presence of the correct record, the usual procedure to delete
  5481.      an indexed file record is the command sequence:  POSN, READ, FREE.
  5482.  
  5483.      BACKSPACE
  5484.      ---------
  5485.      This statement moves the file backwards one record from the current
  5486.      position.  It is only used for random or indexed sequential files.  An
  5487.      end-of-file error is generated if there are no records in the file, or if
  5488.      the file is already positioned at the first record. 
  5489.  
  5490.      COPY
  5491.      ----
  5492.      COPY is used only with data files that have FIDs.  It is used for rapid
  5493.      transfer of data from a file to the screen, from the screen to a file, or
  5494.      from a file to another file.
  5495.  
  5496.      FCOPY
  5497.      -----
  5498.      FCOPY copies a file to a file.  No wild cards are allowed.
  5499.  
  5500.  
  5501.  
  5502.                                Files and File Handling
  5503.                                        Page 78
  5504.  
  5505.  
  5506.  
  5507.  
  5508.  
  5509.  
  5510.  
  5511.      FSEAR
  5512.      -----
  5513.      FSEAR searches a data file on a record-by-record basis for the satisfaction
  5514.      of any logical condition.
  5515.  
  5516.  
  5517.  
  5518.  
  5519.  
  5520.  
  5521.  
  5522.  
  5523.  
  5524.  
  5525.  
  5526.  
  5527.  
  5528.  
  5529.  
  5530.  
  5531.  
  5532.  
  5533.  
  5534.  
  5535.  
  5536.  
  5537.  
  5538.  
  5539.  
  5540.  
  5541.  
  5542.  
  5543.  
  5544.  
  5545.  
  5546.  
  5547.  
  5548.  
  5549.  
  5550.  
  5551.  
  5552.  
  5553.  
  5554.  
  5555.  
  5556.  
  5557.  
  5558.  
  5559.  
  5560.  
  5561.  
  5562.                                Files and File Handling
  5563.                                        Page 79
  5564.  
  5565.  
  5566.  
  5567.  
  5568.  
  5569.  
  5570.  
  5571.                                     ERROR HANDLING
  5572.                                     ==============
  5573.  
  5574.  
  5575.                                        General
  5576.                                        -------
  5577.  
  5578.      There are two basic types of errors that may occur within a Q-PRO 4
  5579.      program:
  5580.  
  5581.       o   Those that are handled automatically within the system.  Examples of
  5582.           automatic errors are:  syntax error (always fatal), or an invalid
  5583.           character typed in a field (recoverable by the operator).  Since these
  5584.           errors are always handled in the same manner by the system (and are
  5585.           inaccessible to the format program), the reader is referred to the
  5586.           Error Section for a list of these errors.
  5587.  
  5588.       o   Those that optionally may be handled by the user program.  Errors
  5589.           which can be handled by the program are termed "trappable" errors. 
  5590.           Error trapping is hierarchical in nature.  There is a hierarchy of
  5591.           error trapping is shown below.
  5592.       
  5593.           1.   Local Error Traps.  A local error trap is designated by the colon
  5594.                (:) and a line number or label at the end of the command.  If a
  5595.                local error trap is designated, it overrides any other error
  5596.                traps.
  5597.  
  5598.           2.   ERRTRAP.  If there is no local error trap ERRTRAP will execute
  5599.                (if present).  Note that ERRTRAP has precedence and overrides
  5600.                PROC ERROR.
  5601.  
  5602.           3.   PROC ERROR.  If there is no local error trap, or ERRTRAP control
  5603.                of the program will go to PROC ERROR.
  5604.  
  5605.      If no error trapping is specified, a trappable error will be handled as a
  5606.      fatal error.
  5607.  
  5608.                                   Local Error Traps
  5609.                                   -----------------
  5610.  
  5611.      Nature of a Local Trap
  5612.      ----------------------
  5613.      Certain statements (generally file-oriented statements and TSEAR) may
  5614.      designate line numbers or labels to act as error traps for that statement
  5615.      only.  These "local traps" override the presence of an ERRTRAP or PROC
  5616.      ERROR (described below).  Functionally the local error trap is analogous to
  5617.      "ON ERROR GOTO XXX" .
  5618.  
  5619.  
  5620.  
  5621.  
  5622.  
  5623.                                     Error Handling
  5624.                                           80
  5625.  
  5626.  
  5627.  
  5628.  
  5629.  
  5630.  
  5631.  
  5632.  
  5633.  
  5634.      Registers
  5635.      ---------
  5636.      In contrast to the more global types of error trapping (PROC ERROR and
  5637.      ERRTRAP), however, the contents of #N0 and #S0 are unchanged in an error
  5638.      condition.  In most circumstances this results in no loss of flexibility,
  5639.      since the type of error trapped is usually predictable, depending on the
  5640.      statement executed.  In the following example, a local error trap is
  5641.      associated with a read statement to detect an end-of-file condition.
  5642.  
  5643.      PROC READREC
  5644.      * Input the next record
  5645.           READ 5 :1001
  5646.      * Load the data field
  5647.           CALL LOADREC
  5648.           END
  5649.      *We go here at file end
  5650.  
  5651.      1001 CLOSE 5
  5652.           ERROR "END OF DATA ENCOUNTERED"
  5653.           CHAIN "MENU"
  5654.           END
  5655.  
  5656.  
  5657.                                       PROC ERROR
  5658.                                       ----------
  5659.  
  5660.      When PROC ERROR Is Invoked
  5661.      --------------------------
  5662.      The standard procedure ERROR receives control when a trappable error occurs
  5663.      and there is no local error trap or ERRTRAP.
  5664.      At the time of the error, the error number (as listed in Appendix A) will
  5665.      be placed in numeric register 0 (#N0), the system level error will be
  5666.      placed in the system error register (#E) and the error message will be
  5667.      placed in string register 0 (#S0).
  5668.  
  5669.      In general the system error register (#E) is more valuable for the low
  5670.      level information needed for debugging.  
  5671.  
  5672.      Example of Use
  5673.      --------------
  5674.      The following is an example of an ERROR procedure.  In this example, the
  5675.      procedure checks for a "file unavailable" error (presumably caused by
  5676.      trying to open a non-existent file) and, if so, displays an error message
  5677.      and returns to the operating system.  Otherwise, the system generated error
  5678.      message is displayed and the statement that caused the error is re-executed
  5679.      if PROC ERROR is terminated with RETURN or END.  A GOTO in PROC ERROR will
  5680.      cause stack overflow problems and, presumably, a call to us for help.
  5681.  
  5682.  
  5683.  
  5684.                                     Error Handling
  5685.                                           81
  5686.  
  5687.  
  5688.  
  5689.  
  5690.  
  5691.  
  5692.  
  5693.      Example of PROC ERROR
  5694.       
  5695.      PROC ERROR
  5696.      * No file error?
  5697.           IF #N0 EQ 13 THEN GOTO 1
  5698.      * Some other error - just display it
  5699.           ERROR #S0
  5700.           END
  5701.  
  5702.      * Display NO FILE error
  5703.      1  ERROR "CAN'T FIND DATA FILE"
  5704.           SYSTEM
  5705.           END
  5706.  
  5707.                                        ERRTRAP
  5708.                                        -------
  5709.  
  5710.      The ERRTRAP facility is used in the same manner as a local error trap,
  5711.      except that it may be used to redirect error trapping to different segments
  5712.      of code.  Each field procedure, for example, could have its own error trap
  5713.      routine.  Note:  error traps set by ERRTRAP override the existence of PROC
  5714.      ERROR.
  5715.      ERRTRAP uses the same registers as PROC ERROR.
  5716.  
  5717.      The following is an example of a procedure with its own error trap.
  5718.  
  5719.  
  5720.      PROC FOPEN
  5721.      * Set error trap
  5722.           ERRTRAP 10
  5723.           OPEN "DATAFILE",1,1
  5724.           MOVE "FILE OPEN" TO STATUS
  5725.      * Done, clear the error trap
  5726.           ERRTRAP
  5727.           NEXT CUSTNO
  5728.      * Error, look for no file error
  5729.      10   IF #N0 EQ 13 THEN GOTO 11
  5730.      * Some other error - display it
  5731.           ERROR #S0
  5732.           END
  5733.  
  5734.      * File not there, create it
  5735.      * Clear the error trap first
  5736.      11   ERRTRAP
  5737.           MAKE "DATAFILE",1,1
  5738.           MOVE "FILE CREATED" TO STATUS
  5739.           END
  5740.  
  5741.      Note that the ERRTRAP line number previously designated as an ERRTRAP is
  5742.      disabled by another ERRTRAP statement that has no line number.
  5743.  
  5744.  
  5745.                                     Error Handling
  5746.                                           82
  5747.  
  5748.  
  5749.  
  5750.  
  5751.  
  5752.  
  5753.  
  5754.  
  5755.  
  5756.  
  5757.      System Error Register - #E
  5758.      --------------------------
  5759.      In all three of the above techniques for handling errors, the error number
  5760.      register (#E) may be examined.  This register contains the specific error
  5761.      code returned by the operating system in response to a file operation
  5762.      request (as opposed to #N0, which returns a Q-PRO 4 level error code).
  5763.  
  5764.  
  5765.  
  5766.  
  5767.  
  5768.  
  5769.  
  5770.  
  5771.  
  5772.  
  5773.  
  5774.  
  5775.  
  5776.  
  5777.  
  5778.  
  5779.  
  5780.  
  5781.  
  5782.  
  5783.  
  5784.  
  5785.  
  5786.  
  5787.  
  5788.  
  5789.  
  5790.  
  5791.  
  5792.  
  5793.  
  5794.  
  5795.  
  5796.  
  5797.  
  5798.  
  5799.  
  5800.  
  5801.  
  5802.  
  5803.  
  5804.  
  5805.  
  5806.                                     Error Handling
  5807.                                           83
  5808.  
  5809.  
  5810.  
  5811.  
  5812.  
  5813.  
  5814.  
  5815.  
  5816.                               LANS and MULTIUSER SYSTEMS
  5817.                               --------------------------
  5818.  
  5819.                                        General
  5820.                                        -------
  5821.  
  5822.      The multiuser or local area network (LAN) poses many complex problems for
  5823.      the application developer.  For the most part, the documentation furnished
  5824.      with the operating system is either sparse or confusing, or both.  Q-PRO 4
  5825.      must work within the constraints of the operating system no matter how
  5826.      illogical its design may be.  This chapter attempts to explain the
  5827.      functioning of the Q-PRO 4 commands and how the operating system handles
  5828.      them.
  5829.  
  5830.      The Q-PRO 4 shareware version is a LAN, Multiuser version.  The multiuser
  5831.      runtime will always run on a matching single user operating system.  For
  5832.      example PC-DOS programs will run with a PC-LAN runtime.
  5833.  
  5834.      Principles
  5835.      ----------
  5836.      The system works on a principle of "mutual exclusion" at the statement
  5837.      level.  This means that, under program control, a record may be locked so
  5838.      that one user will not be changing a record when another user is searching
  5839.      for a record.  Similarly, the programmer has control over the way files are
  5840.      opened, LOCKED, UNLOCKED, and/or READ ONLY.
  5841.  
  5842.      This is achieved by system calls and is transportable from operating system
  5843.      to operating system.  This locking process is always under the programmer's
  5844.      control and is transparent to users.  Q- PRO 4 will try one time to get a
  5845.      data record lock and a setable number of times (set with LRETRY) to get a
  5846.      header record lock before reporting an error (failure to get a lock) if the
  5847.      record is already locked to the programmer.  It is up to the programmer to
  5848.      decide what to do when a lock is attempted and the record is already
  5849.      locked.  It is a must, however, that programs attempt to lock a record
  5850.      before doing a read for update or a record deletion.
  5851.  
  5852.  
  5853.                                   Multiuser Commands
  5854.                                   ------------------
  5855.  
  5856.      The following Q-PRO 4 commands are specifically for multiuser operating
  5857.      system control.  See the commands section for syntax and examples.
  5858.  
  5859.      HOST
  5860.      ----
  5861.      The HOST is set with the HOST statement in the program code, typically in
  5862.      PROC LOAD.  HOST sets the type of multiuser system the application is
  5863.      running under.  NO files may be open when this command is executed.  If
  5864.  
  5865.  
  5866.                                         LAN's
  5867.                                        Page 84
  5868.  
  5869.  
  5870.  
  5871.  
  5872.  
  5873.  
  5874.  
  5875.      MULTIUSER data files are to be shared, the host value must be set to a
  5876.      multiuser value (that is, not SINGLE) or ALL the files may be corrupted if
  5877.      updated.  Once set, the selected HOST remains until running under another
  5878.      HOST is selected or the application returns to the multiuser operating
  5879.      system.
  5880.  
  5881.      RLOCK
  5882.      -----
  5883.      RLOCK is ignored if the system is not in multiuser mode.  If the system is
  5884.      in multiuser mode, it will lock the record on which the file is currently
  5885.      positioned (regardless of what record, if any, is currently in the data
  5886.      buffer).  If the application has previously locked a record in the same
  5887.      file, the lock is released before attempting a new lock, even if the
  5888.      attempt at the new lock is unsuccessful. 
  5889.  
  5890.      An error will occur if the record is locked by another application, an
  5891.      adjacent record in the same sector is locked, or if the file is busy.  The
  5892.      error returned is a file exclusion failure, error code 25.  The programmer
  5893.      may choose to have the application try the lock again or try to lock some
  5894.      other record.  Any other error should be treated as a fatal error.
  5895.      Note that the protocol of locking a position in a file before trying to do
  5896.      something with the record at that position is entirely at the option of the
  5897.      application programmer.  Nothing in multiuser operating systems, at the
  5898.      current level of technology, prevents an application from reading a record
  5899.      locked by someone else, if so desired.
  5900.  
  5901.      RLOCK locks the record position being pointed to in the file buffer.  It
  5902.      unlocks a previous lock if there is one.
  5903.  
  5904.      RUNLOCK
  5905.      -------
  5906.      RUNLOCK unlocks a record that has been locked by the RLOCK command.  
  5907.  
  5908.      LRETRY
  5909.      ------
  5910.      The LRETRY command sets the number of times a lock is attempted.  This
  5911.      value may be increased to help avoid timeouts on waiting for the header. 
  5912.      Be careful when you use this command for you must give the system enough
  5913.      time to react.
  5914.  
  5915.      OPEN and MAKE
  5916.      -------------
  5917.      OPEN and MAKE have two optional keywords after the file number, UNLOCKED
  5918.      and R/O (read/only). By default, a file is opened as read/write and locked. 
  5919.      These keywords can be in any order and need not appear together.  If a file
  5920.      is not opened in the unlocked mode, then only one application can open the
  5921.      file.  (Note: some systems do not support files in locked mode.)  Any other
  5922.      application attempting to use the same file will get the error, 'file
  5923.      unavailable' (error code 6).
  5924.  
  5925.  
  5926.                                         LAN's
  5927.                                        Page 85
  5928.  
  5929.  
  5930.  
  5931.  
  5932.  
  5933.  
  5934.  
  5935.  
  5936.      In almost all applications, but especially applications where unavailable
  5937.      files may occur, to be safe, MAKE all the files during application
  5938.      installation before any other application starts.  With this technique, if
  5939.      error code 6 is returned, the programmer will know it was because the file
  5940.      was locked (not because the file was not there).  This error also may occur
  5941.      if a MAKE is attempted on a file that is locked by another user.  If files
  5942.      are being opened in unlocked mode (shared), a file exclusion lock may occur
  5943.      if the file is already opened by another user and is busy (see notes on
  5944.      file busy).
  5945.  
  5946.      READ
  5947.      ----
  5948.      The READ command can return two additional errors in multiuser mode:
  5949.  
  5950.        1. The first is a file exclusion failure, error code 25 (file was busy). 
  5951.           This does not necessarily mean that the record trying to be read is
  5952.           locked.  Instead, it means that the file was busy processing a request
  5953.           for another application.  The read may be tried again.
  5954.  
  5955.        2. The second additional error is a file sync failure, error code 26.  A
  5956.           sync error may occur under the following two circumstances (or
  5957.           variants thereof):
  5958.  
  5959.             o  the application positions to a record, but before the record is
  5960.                locked and read another application deletes the record.
  5961.             o  The application does a read without NOADV, intending to go to the
  5962.                next record.  If that record is then deleted by some other
  5963.                application before it is read, a sync error can also occur. 
  5964.  
  5965.      WRITE
  5966.      -----
  5967.      The only additional error in multiuser mode is a file exclusion failure. 
  5968.      This can happen if the record being written is locked by some other
  5969.      application.  When a record is inserted into the index file, the record
  5970.      linkages of connecting records must be updated.  If any of these are locked
  5971.      by someone else, the WRITE will fail.  This is important to remember
  5972.      because it can cause what is called a "deadly embrace."  Deadly embrace
  5973.      occurs when both applications have a record locked that will cause the
  5974.      other to fail the write.  Unless one application unlocks the record, they
  5975.      will both continue to fail the write.
  5976.  
  5977.      FREE
  5978.      ----
  5979.      The FREE command is similar to the WRITE command in that a record can not
  5980.      be deleted if one of the records affected is locked.  This will cause a
  5981.      file exclusion failure, as in WRITE.  The error "key not found" (error code
  5982.      32) is returned if the record to be freed was deleted by some other
  5983.      application after the READ but before the FREE.
  5984.  
  5985.  
  5986.                                         LAN's
  5987.                                        Page 86
  5988.  
  5989.  
  5990.  
  5991.  
  5992.  
  5993.  
  5994.  
  5995.  
  5996.  
  5997.      BACKSPACE
  5998.      ---------
  5999.      BACKSPACE will return a file busy error (exclusion failure) or a file sync
  6000.      error, for the same reasons as in read.
  6001.  
  6002.      FSEAR, POSN, and SECURE
  6003.      -----------------------
  6004.      The commands FSEAR, POSN and SECURE also may return a file exclusion
  6005.      failure (error code 25).  During any ISAM file I/O, the header record of
  6006.      the indexed file is locked so that only one application is moving through
  6007.      or updating the index file tree structure.  If an insert takes a very long
  6008.      time because there are many duplicates or the file is grossly out of
  6009.      balance, the other applications will time out waiting for the header and
  6010.      get the file exclusion failure.  This time out is set by LRETRY.
  6011.  
  6012.      LPDETACH
  6013.      --------
  6014.      LPDETACH closes the spool file.
  6015.  
  6016.  
  6017.                                   MULTIUSER - ERRORS
  6018.                                   ------------------
  6019.  
  6020.      #E - The ERROR REGISTER
  6021.      -----------------------
  6022.      #E is a read-only register called the error register.  The contents of this
  6023.      register are the error codes as returned from file operations.  That is,
  6024.      the direct codes returned by the operating system instead of the Q-PRO 4
  6025.      high level error codes.  The possible contents of this register are listed
  6026.      in the operating system manuals.
  6027.  
  6028.  
  6029.      MULTIUSER ERROR CODES
  6030.      ---------------------
  6031.  
  6032.      FILE EXCLUSION LOCK FAILED
  6033.      Trappable as error 25.  System tried LRETRY times to lock record 0 of an
  6034.      indexed file (required for most file operations) and could not get the
  6035.      lock.
  6036.  
  6037.      FILE SYNCH. FAILURE
  6038.      Trappable as error 26.  Files are said to be out of synch when one process
  6039.      reads a record with apparently valid index links, which is then discovered
  6040.      to have been deleted by some other process.
  6041.  
  6042.      BAD HOST STATEMENT
  6043.      Trappable as error 27. A host statement was executed which either did not
  6044.  
  6045.  
  6046.                                         LAN's
  6047.                                        Page 87
  6048.  
  6049.  
  6050.  
  6051.  
  6052.  
  6053.  
  6054.  
  6055.      have a recognizable name, or at a time when all files were not closed.
  6056.  
  6057.      FILE READ-ONLY
  6058.      Trappable as error 28. Pretty obvious what this one means.
  6059.      For multiuser user, be sure you configure your operating system to allow
  6060.      three locks per file, file and record.  (You need only 2 files, if you will
  6061.      not do record-locking in your application).
  6062.  
  6063.  
  6064.  
  6065.  
  6066.  
  6067.  
  6068.  
  6069.  
  6070.  
  6071.  
  6072.  
  6073.  
  6074.  
  6075.  
  6076.  
  6077.  
  6078.  
  6079.  
  6080.  
  6081.  
  6082.  
  6083.  
  6084.  
  6085.  
  6086.  
  6087.  
  6088.  
  6089.  
  6090.  
  6091.  
  6092.  
  6093.  
  6094.  
  6095.  
  6096.  
  6097.  
  6098.  
  6099.  
  6100.  
  6101.  
  6102.  
  6103.  
  6104.  
  6105.  
  6106.                                         LAN's
  6107.                                        Page 88
  6108.  
  6109.  
  6110.  
  6111.  
  6112.  
  6113.  
  6114.  
  6115.                           B I N A R Y   W O R S T A T I O N
  6116.                           =================================
  6117.  
  6118.                                      Introduction
  6119.                                      ============
  6120.  
  6121.  
  6122.      Complete Development System
  6123.      ---------------------------
  6124.      Binary Workstation (BW) is a complete development management system.  BW is
  6125.      intuitive in use and extremely flexible.  There is no master menu and you
  6126.      probably will never miss it!  Indeed, after a cursory look at the
  6127.      documentation and a few minutes using BW, you will probably consign the
  6128.      documentation to gather dust wherever you toss unused documentation.
  6129.  
  6130.      Multiple Files
  6131.      --------------
  6132.      Binary WorkStation can store several of your source files in memory at the
  6133.      same time.  You can switch from module to module with a press of a key. 
  6134.      You can edit each individually and even copy parts from on to another.
  6135.  
  6136.      Syntax Checker
  6137.      --------------
  6138.      At the press of a key, your entire program will be checked for syntax
  6139.      errors saving you hours of debugging.
  6140.  
  6141.      Operating System Shell
  6142.      ----------------------
  6143.      While you are in BW you can run any other program and then return to the
  6144.      same line of code.
  6145.  
  6146.  
  6147.                                    Multiple Editors
  6148.                                    ----------------
  6149.  
  6150.      Text Editor
  6151.      ----------
  6152.      Binary Workstation is a fully featured text editor for editing Q-PRO 4
  6153.      programs or ASCII files.  You can import/export Q-PRO 4 program files or
  6154.      ASCII files also.
  6155.  
  6156.      FID Editor
  6157.      ----------
  6158.      The File Item Descriptor (FID) editor is used to create and edit the file
  6159.      descriptions.
  6160.  
  6161.      Screen Editor
  6162.      -------------
  6163.      Used to "paint" screens, you paint the background color, specify the window
  6164.  
  6165.  
  6166.                               Binary WorkStation Editor
  6167.                                        Page 89
  6168.  
  6169.  
  6170.  
  6171.  
  6172.  
  6173.  
  6174.  
  6175.      size and location, specify the active field color, specify the screen data
  6176.      entry field colors, and define the screen data entry fields.
  6177.  
  6178.      Miscellaneous Features
  6179.      ----------------------
  6180.      Other outstanding features of BW are: Alt key macros, History log file, On
  6181.      Screen Clock and Backup file option.
  6182.  
  6183.  
  6184.                                      Starting Up
  6185.                                      -----------
  6186.  
  6187.      Setting Up DOS for BW 
  6188.      ---------------------
  6189.      Binary WorkStation has an options file.  In fact, it can have an options
  6190.      file for every subdirectory you use it in.  Or it can have one options file
  6191.      that is in a directory specified by the DOS variable, <BI>BW.  We recommend
  6192.      that, at first, you use the DOS variable.
  6193.  
  6194.      Binary WorkStation has extensive help screens.  You can refer to them from
  6195.      any subdirectory where you happen to be if you use the DOS variable BWHELP.
  6196.  
  6197.      Also, so you can use it anywhere, the subdirectory with Binary WorkStation
  6198.      in it should be on the path.
  6199.  
  6200.      Setting the options
  6201.      -------------------
  6202.      From the command line, type: BW<ret> 
  6203.  
  6204.      The options screen will be displayed.  If an option file exists in the
  6205.      current directory or on the path, the previously selected options are
  6206.      displayed.
  6207.  
  6208.      Use the TAB key to move from field to field.  Pressing ENTER will save the
  6209.      options and bring up the editing screen.
  6210.  
  6211.      Current File [        ]       Enter the path and name of the file to be
  6212.                                    edited.  When you leave this screen, the
  6213.                                    named file will be displayed.
  6214.  
  6215.      Vertical Scroll Lines [16]    Number of lines to scroll when Page Up/Page
  6216.                                    Down are executed.
  6217.  
  6218.      Backup File [N]               A backup file of the file you are editing
  6219.                                    will be maintained if you enter a "Y"  
  6220.  
  6221.      Clock [Y]                     If Y is selected, the time will be displayed
  6222.                                    in the lower right corner of the screen.
  6223.  
  6224.  
  6225.  
  6226.                               Binary WorkStation Editor
  6227.                                        Page 90
  6228.  
  6229.  
  6230.  
  6231.  
  6232.  
  6233.  
  6234.  
  6235.      Q-PRO 4 File [Y]              If "Y" the editor will assume Q-PRO file
  6236.                                    format.  If "N" it will assume a standard
  6237.                                    ASCII file.  You need not set this flag, BW
  6238.                                    can figure out which one it has when the file
  6239.                                    to be edited is loaded.
  6240.  
  6241.      Directory Pattern [      ]    This pattern will govern the files to be
  6242.                                    displayed when the FILES option is selected
  6243.                                    when in the editor.
  6244.  
  6245.      FID Path [      ]             If you are going to use the FID editor
  6246.                                    feature, you enter the path for the defined
  6247.                                    FIDs.
  6248.  
  6249.      FID Names                     Up to 20 may be specified.
  6250.  
  6251.      History Log File [N]          If "Y", a log file, HISTLOG.BW will be kept
  6252.                                    of all functions, save, etc. with function
  6253.                                    and date/time.<
  6254.  
  6255.      Text Lines (min 500) [     ]  Sets the maximum number of lines of text
  6256.                                    allowed in a file.  Us it to make more room
  6257.                                    for multiple files.
  6258.  
  6259.  
  6260.      Printer: Char. Per Line [80]  Sets the number of characters per line. 
  6261.                                    Default is 80.
  6262.  
  6263.      Lines Per Page [55]           Sets the number of lines to print on hard
  6264.                                    copy.  Default is 55.
  6265.  
  6266.      DOS variables
  6267.      -------------
  6268.      If you set the DOS variable BW with the DOS SET command in AUTOEXEC.BAT
  6269.      this way:
  6270.  
  6271.           SET BW=<editor directory>
  6272.  
  6273.           only one option file will be used for all directories.
  6274.  
  6275.           If you set the DOS variable BWHELP with the DOS SET command in
  6276.           AUTOEXEC.BAT this way:
  6277.  
  6278.           SET BWHELP=\<editor directory>
  6279.       
  6280.           then the help screens will be displayed from any directory you are
  6281.           working in
  6282.  
  6283.      Uses for the Option File
  6284.  
  6285.  
  6286.                               Binary WorkStation Editor
  6287.                                        Page 91
  6288.  
  6289.  
  6290.  
  6291.  
  6292.  
  6293.  
  6294.  
  6295.      ------------------------
  6296.      If you are developing multiple applications, it is suggested that BW be in
  6297.      its own directory on the DOS path.  Then each application may have its own
  6298.      subdirectory and options set.
  6299.  
  6300.  
  6301.  
  6302.  
  6303.  
  6304.  
  6305.  
  6306.  
  6307.  
  6308.  
  6309.  
  6310.  
  6311.  
  6312.  
  6313.  
  6314.  
  6315.  
  6316.  
  6317.  
  6318.  
  6319.  
  6320.  
  6321.  
  6322.  
  6323.  
  6324.  
  6325.  
  6326.  
  6327.  
  6328.  
  6329.  
  6330.  
  6331.  
  6332.  
  6333.  
  6334.  
  6335.  
  6336.  
  6337.  
  6338.  
  6339.  
  6340.  
  6341.  
  6342.  
  6343.  
  6344.  
  6345.  
  6346.                               Binary WorkStation Editor
  6347.                                        Page 92
  6348.  
  6349.  
  6350.  
  6351.  
  6352.  
  6353.  
  6354.  
  6355.                                    The Text Editor
  6356.                                    ===============
  6357.  
  6358.      Running from the Command Line
  6359.      -----------------------------
  6360.      From the command line type:  BW <file name><ret>
  6361.  
  6362.      If an options file exists on the logged directory or on the path, the
  6363.      options screen will be displayed momentarily.  Then you will be moved to
  6364.      the program code editor.
  6365.  
  6366.      Overview
  6367.      --------
  6368.      The text editor has two editing modes, INSERT character and TYPEOVER
  6369.      character.  The status is displayed on the upper right and the Insert key
  6370.      toggles the mode.
  6371.  
  6372.      ESC Key
  6373.      -------
  6374.      The ESC key acts as a "cancel" key.  For example, if you have brought up a
  6375.      dialog screen, pressing ESC will bring you back.  
  6376.  
  6377.      All other functions are executed either by pressing function keys or a
  6378.      control characters.  The current function that will be activated by the
  6379.      function key is displayed at the bottom of the screen as a menu line.  A
  6380.      typical editor screen is shown below:
  6381.  
  6382.      Status Line    The top line is the status line.  From left to right the
  6383.                     fields are:
  6384.  
  6385.      library.qne    The name of the file currently being edited.
  6386.  
  6387.      Line=          The line number that the cursor is currently on.
  6388.  
  6389.      Col=           The current column of the cursor.
  6390.  
  6391.      Total Lines=   Total lines in the program.  This reserves space for your
  6392.                     program files.  Clearly, the smaller the programs, the less
  6393.                     total lines you should specify and the more programs you can
  6394.                     have in memory simultaneously. 
  6395.  
  6396.      Insert=        This is a general mode setting switch.  It will be ON in the
  6397.                     INSERT character mode or OFF in the DELETE character mode. 
  6398.                     Toggle the mode by pressing the Insert key.  Several
  6399.                     functions work differently depending on whether INSERT mode
  6400.                     is ON or OFF.
  6401.  
  6402.  
  6403.  
  6404.  
  6405.  
  6406.                               Binary WorkStation Editor
  6407.                                        Page 93
  6408.  
  6409.  
  6410.  
  6411.  
  6412.  
  6413.  
  6414.  
  6415.      Function       Insert ON                      Insert OFF
  6416.      --------       ----------                    -----------
  6417.  
  6418.      TAB            Moves the text at the cursor
  6419.                     position 4 spaces to the right.
  6420.  
  6421.      Return         Inserts a carriage return     Moves the cursor to the 
  6422.           line feed at the cursor       beginning of the next line. 
  6423.                     position.
  6424.  
  6425.      Any key        Inserts the character at      Overwrites the character
  6426.                     the cursor position           at the current character
  6427.                                                   position.
  6428.  
  6429.      10:16am   The system time
  6430.  
  6431.      Menu Line
  6432.      ---------
  6433.      Bottom Line - The bottom line is the menu line.  Because the menu line can
  6434.      display only eight functions, the menu line itself is changed by pressing
  6435.      F10 to scroll the menu forward, F9 to scroll the menu backward.
  6436.  
  6437.      From the main BW screen, dialogue screens and specification screens are
  6438.      summoned for various functions such as text search and FID display and
  6439.      generation.
  6440.  
  6441.      There are four main menu lines:
  6442.  
  6443.      Line   F1      F2     F3       F4     F5       F6     F7      F8
  6444.       
  6445.      0    Top     Bottom  Pg Up   Pg Dn   Insert  Delete  Fields  Screen
  6446.      1    Load    Update  Unload  Save/x  Swap    Exit    FIDs    Exec
  6447.      2    Search  Sr/Rep  Again   ASCII   Print   Eject   Syntax  Regs
  6448.      3    FIDgen  Files   Merge   Optns   Insert  Delete  Word    Help!
  6449.      4    SetMrk  MovBlk  CopyBlk DelBlk  Line#s  Un-Del  Goto    Help!
  6450.  
  6451.      This is what will happen with each selection:
  6452.  
  6453.      The accelerator key is shown in <> 
  6454.  
  6455.      Top       Move the cursor to the beginning of the file.  <HOME key>
  6456.  
  6457.      Bottom    Move the cursor to the bottom of the file.  <END key>
  6458.  
  6459.      Pg Up     Move the page up by the number of lines specified in Vertical
  6460.                Scroll in the Editor Options screen.  <PgUp key>
  6461.  
  6462.      Pg Dn     Move the page down by the number of lines specified in Vertical
  6463.                Scroll in the Editor Options screen.  <PgDn key>
  6464.  
  6465.  
  6466.                               Binary WorkStation Editor
  6467.                                        Page 94
  6468.  
  6469.  
  6470.  
  6471.  
  6472.  
  6473.  
  6474.  
  6475.  
  6476.      Insert    Insert a line at the current cursor position.  <Control C>  
  6477.  
  6478.      Delete    Delete a line at the current cursor position.  <Control D>
  6479.  
  6480.      Fields    Displays the screen data field specifications.  <Control F>
  6481.  
  6482.      Screen    Brings up the window definition screen ready for editing.  See
  6483.                the Screen Editor chapter for more detail.  <Shift-F8>
  6484.  
  6485.      Load      Load a file into the editor.  You may Load up to eight files into
  6486.                memory as long as you have the memory.  BW has an overhead of
  6487.                approximately 20K per file loaded.  The dialogue screen below
  6488.                will be displayed. <Control L>
  6489.        
  6490.                The files currently loaded in RAM will be displayed.
  6491.  
  6492.                Load File:file1.qne
  6493.                The most recently loaded file's name will be displayed.  To load
  6494.                another file, type the name and press enter. 
  6495.       
  6496.      Update    Updates the currently loaded file to disk.  The dialogue screen
  6497.                show below is displayed:  <Control U>
  6498.  
  6499.      Save this file [Y]
  6500.                     BW assumes that you want to save a file so it defaults to Y.
  6501.  
  6502.                     Save in Q-PRO 4 format? [Y]
  6503.  
  6504.                Enter Y if you want to save this file in Q-PRO 4 format, i.e.,
  6505.                with screens.  If you want to save it in ASCII format, press N.
  6506.  
  6507.                File name [              ] 
  6508.                Type the name of the file that you want to save.
  6509.  
  6510.      Unload    A dialog screen displays a list of all files Loaded.
  6511.  
  6512.                Entering a Y in the box will keep the file loaded.  Entering an N
  6513.                will unload the file.  You may keep or discard as many files as
  6514.                you want.
  6515.  
  6516.                Unloading a file does not save it.  If you have edited a file and
  6517.                want to keep the results, update it before unloading it. 
  6518.  
  6519.                     The cursor will be in the Unload? column.  Enter a Y in the
  6520.                     appropriate box to remove the file from memory. 
  6521.  
  6522.      Save/X    Saves all the files that are currently loaded in memory and exits
  6523.                BW.  The same dialogue screen as in SAVE will be displayed for
  6524.  
  6525.  
  6526.                               Binary WorkStation Editor
  6527.                                        Page 95
  6528.  
  6529.  
  6530.  
  6531.  
  6532.  
  6533.  
  6534.  
  6535.                each file. <Shift-F4>
  6536.  
  6537.      Swap      Swap unloads the current program file from the screen and loads
  6538.                the next one in sequence.  BW keeps track of where you are in
  6539.                each file and returns you to that line when the program is
  6540.                swapped in.  <Control O>
  6541.  
  6542.      Exit      Leave BW.  <Control X>
  6543.  
  6544.      FIDs      Displays a dialogue screen to select the fid to be displayed. 
  6545.                Only FIDs that have been defined in Editor Options will be
  6546.                displayed.  For more information, see the FID Generator section. 
  6547.                <Control P>
  6548.  
  6549.      Execute   Brings up a dialogue screen to select a program to run.  It
  6550.                defaults to the program currently loaded.
  6551.  
  6552.                     You may execute any executable program, e.g. DIR,FORMAT,
  6553.                     etc.  If you are executing QNE, BW will automatically put a
  6554.                     $ in front of the file name to turn off the QNE banner. 
  6555.                     After execution it will ask you to hit any key to return to
  6556.                     BW and display the text file that was in memory.  The
  6557.                     dialogue box shown below will be displayed:  <Control Q>
  6558.  
  6559.                     The most recently executed command line will be displayed. 
  6560.                     Enter a new one to run a different program.  You may edit
  6561.                     the line with insert/delete keys.  The dollar sign ($) tells
  6562.                     the Q-PRO 4 interpreter to suppress its banner.
  6563.  
  6564.                Notes on Execute:
  6565.                -----------------
  6566.                This option will execute the program on disk.  Therefore, if you
  6567.                are executing the program just edited and in memory, you must
  6568.                update the program currently loaded to insure that what you have
  6569.                edited is executed.  You will get a warning.
  6570.       
  6571.                For proper return from the executed Q-PRO 4 program, do not use
  6572.                FORMLOAD.
  6573.  
  6574.      Search    Displays a dialogue screen for setting the search criteria.
  6575.                <Control S>
  6576.  
  6577.                The fields are used as follows
  6578.  
  6579.                Search for [        ]    The exact string to be searched for.  BW
  6580.                                         will search for this string throughout
  6581.                                         the entire file.
  6582.  
  6583.                Ignore case [Y]          This instructs BW whether the search is
  6584.  
  6585.  
  6586.                               Binary WorkStation Editor
  6587.                                        Page 96
  6588.  
  6589.  
  6590.  
  6591.  
  6592.  
  6593.  
  6594.  
  6595.                                         case sensitive or not.  The default is
  6596.                                         Y.
  6597.  
  6598.                Quote Character [~]      Use this character for when you are
  6599.                                         looking for a quote "".  Although the
  6600.                                         default is tilde, you may use any
  6601.                                         character.
  6602.        
  6603.      Sr/Rep    Displays a dialogue screen  for setting the search and replace
  6604.                criteria.  <Control T>
  6605.  
  6606.                Search for [        ]    The exact string to be searched for.  BW
  6607.                                         will search for this string throughout
  6608.                                         the entire file.
  6609.  
  6610.                Replace with [      ]    Replace the any string that matches the
  6611.                                         search criteria with the string in shown
  6612.                                         here.
  6613.  
  6614.                Ask before replace? [Y]  Stop and ask before replacing the string
  6615.                                         with the new value.
  6616.       
  6617.                Ignore case [Y]          This instructs BW whether the search is
  6618.                                         case sensitive or not.  The default is
  6619.                                         Y.
  6620.  
  6621.                Quote Character [~]      Use this character for when you are
  6622.                                         looking for a quote "".  Although the
  6623.                                         default is tilde, you may use any
  6624.                                         character.
  6625.  
  6626.      Again     Perform the search again.  <Control A>
  6627.  
  6628.      ASCII     Display a chart of the ASCII values of decimal characters.
  6629.  
  6630.      Print     Print the program file.  <Shift-F5>
  6631.  
  6632.      Eject     Send a form feed to the list device.
  6633.  
  6634.      Syntax    Invokes the fearsome syntax checker.  It goes through your code
  6635.                from the current cursor position to the end looking for syntax
  6636.                errors.  Upon finding one, it will stop on that line, give an
  6637.                error message, and highlight that line.  <Control W>
  6638.  
  6639.      Regs      Displays all registers that are used.  <Control R>
  6640.  
  6641.      FIDGen    Invokes the FID generator.  See the FID Generator section for
  6642.                more details. <Control V>
  6643.  
  6644.  
  6645.  
  6646.                               Binary WorkStation Editor
  6647.                                        Page 97
  6648.  
  6649.  
  6650.  
  6651.  
  6652.  
  6653.  
  6654.  
  6655.      Files     Displays a directory of files that meet the directory pattern set
  6656.                in the Editor Option Screen.  
  6657.  
  6658.      Merge     Merge an external file with the characteristics in a dialogue
  6659.                screen at the current cursor location. <Shift-F9>
  6660.  
  6661.                Fill in these fields as discussed below:
  6662.  
  6663.                Merge File:    The name, including drive and directory, of the
  6664.                               file.
  6665.  
  6666.                Include Program Text? [ ]     Enter Y or N.  If Y, the text of
  6667.                                              the ASCII file or the program text
  6668.                                              from a Q-PRO 4 file will be
  6669.                                              inserted.
  6670.  
  6671.                Include Screen? [ ] Enter Y or N.  If Y, the screen of the Q-PRO
  6672.                                    4 file will be inserted.
  6673.         
  6674.      Optns     Display the Editor Options Screen
  6675.  
  6676.      Word      Move the cursor from one word to another.  
  6677.  
  6678.      Help!     Display help screen.
  6679.  
  6680.      Set Mrk   Define blocks for block operations.  Set the beginning of the
  6681.                block by placing the cursor at the location to be marked and
  6682.                press the Set Mark key.  Mark the end similarly.  <Alt-F1>
  6683.  
  6684.                Blocks are assumed to be complete lines.  No partial lines are
  6685.                allowed.
  6686.  
  6687.                To mark a single line, place the cursor at the beginning of the
  6688.                line and press the key twice.
  6689.  
  6690.      Move Blk  Move the marked block to the current cursor location.  Move Block
  6691.                will not move a block from one loaded program to another after a
  6692.                SWAP.  <Alt-F2>
  6693.  
  6694.      Cpy Blk   Replicate the marked block at the current cursor location.
  6695.  
  6696.                You can copy a block as many times as you wish.  You may also
  6697.                copy the block from one file to another after a SWAP.  <Alt-F3>
  6698.  
  6699.      Del Blk   Delete the marked block.  You may delete blocks from one file to
  6700.                another.  <Alt-F4>
  6701.  
  6702.      Line #s   This function toggles the display of paragraph numbers on the
  6703.                left border of the screen. <Shift-F7>
  6704.  
  6705.  
  6706.                               Binary WorkStation Editor
  6707.                                        Page 98
  6708.  
  6709.  
  6710.  
  6711.  
  6712.  
  6713.  
  6714.  
  6715.  
  6716.      Un-Del    This function puts the most recently deleted line at the current
  6717.                cursor position.  When using the delete line function, up to 100
  6718.                lines are stored that may be undeleted.  <Shift-F6>
  6719.  
  6720.      Goto      Jumps the cursor to a line number in a Q-PRO 4 program file or an
  6721.                ACSII file.  <Control G>
  6722.  
  6723.      Help!     Display help screen.  
  6724.  
  6725.  
  6726.                                  Other Key Functions
  6727.                                  -------------------
  6728.  
  6729.      Standard keys
  6730.      -------------
  6731.      These keys perform the usual functions: 
  6732.      INS       DEL       UP        DOWN      LEFT      RIGHT 
  6733.      PgUp      PgDn      HOME      END       BACKSPACE ENTER 
  6734.      TAB       BACKTAB
  6735.  
  6736.  
  6737.      Accelerator Keys
  6738.      ----------------
  6739.      The accelerator keys execute the functions directly.  The accelerators are
  6740.      executed by pressing the Ctrl key and the letter at the same time.  They
  6741.      are:
  6742.       
  6743.      Control Key      Function 
  6744.      A         Search Again
  6745.      B         Go to the beginning of the Line
  6746.      E         Go to the end of the Line
  6747.      F         Fields 
  6748.      G         Goto a line number
  6749.      L         Load another file in RAM
  6750.      N         Unload a file in RAM
  6751.      O         Swap the displayed file for another
  6752.      P         Display FID
  6753.      Q         Execute
  6754.      R         Display registers in use
  6755.      S         Search
  6756.      T         Search/Replace
  6757.      U         Update the file in RAM onto disk
  6758.      V         Invoke the FID Generator
  6759.  
  6760.      W         Invoke syntax checker
  6761.      X         Exit from BW
  6762.  
  6763.      Shifted Key                Function
  6764.  
  6765.  
  6766.                               Binary WorkStation Editor
  6767.                                        Page 99
  6768.  
  6769.  
  6770.  
  6771.  
  6772.  
  6773.  
  6774.  
  6775.  
  6776.      F3        Flip bottom line of display
  6777.      F4        Update/Exit
  6778.      F5        Print
  6779.      F6        Undelete
  6780.      F7        Display Line Numbers
  6781.      F8        Go to screen editor
  6782.      F9        Merge another file
  6783.  
  6784.      ALT Key                 Function
  6785.  
  6786.      F1        Set Mark
  6787.      F2        Move marked block
  6788.      F3        Copy marked block
  6789.      F4        Delete marked block
  6790.  
  6791.      Other Keys
  6792.      ----------
  6793.      Other standard keys have expanded functions.  They are:
  6794.  
  6795.      Home           Move to the beginning of file.
  6796.      End            Move to the end of file.
  6797.      Backspace      This is a destructive backspace.  If you delete an entire
  6798.                     line, the next line will be moved up.
  6799.      Del            Deletes the character at the current character location.  If
  6800.                     the cursor is at the end of a line, text from the next line
  6801.                     will be appended to the current line. 
  6802.  
  6803.  
  6804.  
  6805.  
  6806.                                     Screen Editor
  6807.                                     =============
  6808.  
  6809.      Screen Definition
  6810.      -----------------
  6811.      The definitions of the screens are kept in the program file. The screen 
  6812.      mode has its own menu line that works slightly differently than the program
  6813.      edit menu line.  It scrolls forward only by pressing F10.  The next menu
  6814.      line to be displayed is always displayed.
  6815.  
  6816.      The Insert and Delete keys remain functional as insert character and delete
  6817.      character.
  6818.  
  6819.      Building a Screen
  6820.      -----------------
  6821.      All Q-PRO 4 screens are built in the "What-you-see-is-what-you-get"
  6822.      (WYSIWYG) mode.
  6823.  
  6824.  
  6825.  
  6826.                               Binary WorkStation Editor
  6827.                                        Page 100
  6828.  
  6829.  
  6830.  
  6831.  
  6832.  
  6833.  
  6834.  
  6835.      Screen Constants
  6836.      ----------------
  6837.      For constants (or labels or fixed fields or background, whatever you use
  6838.      for terminology) on the screen, just move the cursor where you want the
  6839.      constants and type them. 
  6840.  
  6841.      Screen Data Entry Fields
  6842.      ------------------------
  6843.      For data entry fields, invoke the EDIT FLD option on the menu as discussed
  6844.      below.
  6845.  
  6846.      The menu lines are:
  6847.  
  6848.  
  6849.  
  6850.  
  6851.  
  6852.  
  6853.  
  6854.  
  6855.  
  6856.  
  6857.  
  6858.  
  6859.  
  6860.  
  6861.  
  6862.  
  6863.  
  6864.  
  6865.  
  6866.  
  6867.  
  6868.  
  6869.  
  6870.  
  6871.  
  6872.  
  6873.  
  6874.  
  6875.  
  6876.  
  6877.  
  6878.  
  6879.  
  6880.  
  6881.  
  6882.  
  6883.  
  6884.  
  6885.  
  6886.                               Binary WorkStation Editor
  6887.                                        Page 101
  6888.  
  6889.  
  6890.  
  6891.  
  6892.  
  6893.  
  6894.  
  6895.  
  6896.        F1        F2        F3      F4       F5       F6     F7      F8
  6897.      Edit Fld  Next Fld  HLT On  HLT Off  Insert  Delete   Field    Edit
  6898.      Screen    FIDS      Reps    Import   Insert  Delete!  Help     Edit
  6899.      Graphics
  6900.       
  6901.      Edit Fld       Displays the field definition window:
  6902.  
  6903.                     See the Programmer's Reference section for a detailed
  6904.                     discussion of field characteristics.  Only the field that
  6905.                     the cursor is currently on is editable.  Enter re-displays
  6906.                     the screen.
  6907.  
  6908.           Field Name     The name of the screen data field.
  6909.  
  6910.           Len            The length of the screen data field, 1 to 255
  6911.                          characters.
  6912.  
  6913.           Row            The row where the screen data field is located.  This
  6914.                          row is put in automatically by Binary WorkStation but
  6915.                          you may change it to move the screen data field.
  6916.  
  6917.           Col            The column where the screen data field is located. 
  6918.                          This row is put in automatically by Binary WorkStation
  6919.                          but you may change it to move the screen data field.
  6920.  
  6921.           Type           This is a two character field.  The first character is
  6922.                          the attribute and the second is blank=no edit,
  6923.                          ?=invisible field, or = for autoduplicate.
  6924.  
  6925.           Just           This is the field justification.  You can use L for
  6926.                          left justified, R for right justified, C for center or
  6927.                          N for none.
  6928.  
  6929.           Fill Char      This specifies the character to be used to left fill
  6930.                          the screen data field.  It is typically a zero (0) for
  6931.                          left zero fill.
  6932.  
  6933.           May Ent        A "Y" here allows the user to enter data in the field. 
  6934.                          You could have a field for program remarks only.  Here
  6935.                          the field would be N which would not let the user enter
  6936.                          data.
  6937.  
  6938.           Must Ent       If "Y", the user must enter at least one character in
  6939.                          the field.
  6940.  
  6941.           Must Fill      If "Y", the user must not only enter data in the field,
  6942.                          but must full it completely.
  6943.  
  6944.  
  6945.  
  6946.                               Binary WorkStation Editor
  6947.                                        Page 102
  6948.  
  6949.  
  6950.  
  6951.  
  6952.  
  6953.  
  6954.  
  6955.           Must Tab       If Y, the user must press the TAB key to exit the
  6956.                          field.  If it is N, the user may press TAB to exit the
  6957.                          field or be moved to the next field automatically when
  6958.                          the field is filed.
  6959.  
  6960.           Proc Name      The name of the procedure to execute when the user
  6961.                          exits the field.
  6962.  
  6963.      Hlt On         Turns on the highlighting at the point where the cursor is
  6964.                     located.  On the IBM PC, the default highlighting is reduced
  6965.                     intensity.  Highlighting requires a character position on
  6966.                     the screen.  With the full distribution version of Q-PRO 4,
  6967.                     you can modify the highlighting to your own satisfaction.
  6968.  
  6969.      Hlt Off        Returns the highlighting to standard.   
  6970.  
  6971.      Edit           Leave the screen editor.
  6972.  
  6973.      FIDs           On this screen will be displayed any FID file that you
  6974.                     designated on the option screen.  You may select one of the
  6975.                     pre-designated FIDs by entering its number.
  6976.  
  6977.      Reps           Display a dialogue screen.  Enter a number of reps while
  6978.                     positioned on a previously defined field will reproduce the
  6979.                     defined field the number of reps time, vertically.  BW will
  6980.                     generate names for the fields.
  6981.  
  6982.      Import         This will format the current file into a Q-PRO 4 Help Screen
  6983.                     or Q-PRO 4 Background Screen format.  It takes the first 24
  6984.                     lines in the program file and moves them to the screen.
  6985.  
  6986.      HELP!          Displays a help window.
  6987.  
  6988.      Graphics Mode  Turn Graphics mode on.  Graphics are drawn on the screen
  6989.                     with the cursor keys and the function keys.
  6990.  
  6991.      Next Fld       Moves cursor to next defined screen data field.
  6992.  
  6993.      HLT On         Turns highlights on at the current cursor location.
  6994.                     Highlight for PC-DOS is REDUCED INTENSITY.  You MUST leave a
  6995.                     position for the highlight.  
  6996.  
  6997.      HLT Off        Turns highlights off at the current cursor position.
  6998.  
  6999.      Insert         Insert a line at the current cursor position.
  7000.  
  7001.      Delete         Delete a line at the current cursor position.
  7002.  
  7003.      Fields         Display the specification for all defined screen data
  7004.  
  7005.  
  7006.                               Binary WorkStation Editor
  7007.                                        Page 103
  7008.  
  7009.  
  7010.  
  7011.  
  7012.  
  7013.  
  7014.  
  7015.                     fields.
  7016.  
  7017.                                     Fid Generator
  7018.                                     =============
  7019.  
  7020.  
  7021.                                     The FID System
  7022.                                     --------------
  7023.  
  7024.      The Binary Workstation File Item Descriptor Generator (FID) is used to
  7025.      build and maintain descriptions of file records (called FID files).  It
  7026.      provides a program-independent means of maintaining data file formats. 
  7027.      With FID, changes to file formats may be made without regard to any
  7028.      programs which reference these files, since all references to file fields
  7029.      is done on a symbolic (field name) basis.
  7030.  
  7031.      Other features of the FID system are:
  7032.  
  7033.             o  unlimited number of fields in a record.
  7034.             o  optional overlapping of file data field (called realignment). 
  7035.                This allows varying record formats within a data file.
  7036.             o  replicated fields within a record.  This allows fields to be
  7037.                referenced within Q-PRO 4 as if they were arrays.
  7038.             o  automatic documentation of record formats.
  7039.  
  7040.  
  7041.                                       FID Files
  7042.                                       ---------
  7043.  
  7044.      Restrictions
  7045.      ------------
  7046.      The information about record layouts is contained in a file separate from
  7047.      the data file, called a "FID" file.  A FID file may have any name, and
  7048.      reside on any drive or directory.
  7049.  
  7050.      Commands to associate data files with FID files at open or creation time
  7051.      are described in the Programmer's Reference Manual.
  7052.  
  7053.      FID Dialog Screen
  7054.      -----------------
  7055.      First the FID dialogue screen is displayed.  If any .FIDs are on the FID
  7056.      path, as defined in the options screen, they will be shown on this screen.
  7057.  
  7058.      If the FID file you want to edit is shown on the list on the top of the
  7059.      screen, enter its number and press enter.  Otherwise, type the FID file
  7060.      name and press enter.  This screen will display: 
  7061.  
  7062.      Main FID Screen
  7063.  
  7064.  
  7065.  
  7066.                               Binary WorkStation Editor
  7067.                                        Page 104
  7068.  
  7069.  
  7070.  
  7071.  
  7072.  
  7073.  
  7074.  
  7075.      Editing
  7076.      You can move the cursor freely within the screen displayed to change
  7077.      currently displayed data or enter new data.  
  7078.  
  7079.      Item Name      In this column you specify the name of the FID field.  This
  7080.                     name must follow the standard naming conventions.
  7081.  
  7082.      Len.           This is the length of the FID field.  It can be 1 to 255
  7083.                     characters in length.
  7084.  
  7085.      Type           The FID field type is either alphanumeric (X) or numeric
  7086.                     (N).
  7087.       
  7088.      Description    You may enter here any description that helps document the
  7089.                     field.
  7090.  
  7091.      Reps           The number of times this field is repeated in the file. 
  7092.                     Using this feature allows you to have file arrays.  You may
  7093.                     dimension the array from 1 to 64K.
  7094.  
  7095.                     An element in the array is called out in your program in
  7096.                     this format:
  7097.  
  7098.                          $FID_name[file #, element]
  7099.  
  7100.                               file #    The file number that uses this FID.
  7101.                               element   An integer literal or an expression that
  7102.                                         evaluates to an integer.  Note:  The
  7103.                                         element numbers start at 0.
  7104.       
  7105.                          Examples:
  7106.  
  7107.                               $FED_TAX[1,0]       The first element in file 1,
  7108.                                                   field FED_TAX.
  7109.  
  7110.  
  7111.                               $FED_TAX[1, (#n0-1)]     The #n0-1th element in
  7112.                                                        file 1, field FED_TAX
  7113.        
  7114.  
  7115.      F1 - Page Up        Scroll the FID down a page (if it is long enough).
  7116.  
  7117.      F2 - Page Down      Scroll the FID up a page.
  7118.  
  7119.      F3 - Load FID file  Moves the cursor to the top line awaiting a FID file
  7120.                          name.  After you type the name and press enter, the FID
  7121.                          file (assuming it exists) will be loaded.
  7122.  
  7123.      F4 - Update FID file     This selection allows a file description to be
  7124.  
  7125.  
  7126.                               Binary WorkStation Editor
  7127.                                        Page 105
  7128.  
  7129.  
  7130.  
  7131.  
  7132.  
  7133.  
  7134.  
  7135.                               stored as a FID file on disk.  If the FID file
  7136.                               previously existed (if there is already a file by
  7137.                               the same name on the disk), then that file will be
  7138.                               renamed to name.BFD.  This is so that any
  7139.                               previously existing data file might be regenerated
  7140.                               using the old .BFD FID file as the original
  7141.                               description, and the new FID file as the desired
  7142.                               description.
  7143.  
  7144.                               If a .BFD file is already found to exist, then FID
  7145.                               assumes that this is an old version yet to be used
  7146.                               for regeneration and no new .BFD file is
  7147.                               generated.  Any file with the same name as the
  7148.                               current FID file is deleted.
  7149.       
  7150.      F5 - Insert Field   Pressing this key opens up a line for inserting a new
  7151.                          FID field definition.
  7152.  
  7153.      F6 - Delete Field   Pressing this key deletes the FID field definition at
  7154.                          the current cursor location.
  7155.  
  7156.      F7 - Define Keys    This selection will brings up a window, shown below, at
  7157.                          the bottom of the screen to define the file key.
  7158.  
  7159.                          This screen defines what fields make up each key. 
  7160.                          Fields need not be adjacent.  Keys  must be specified
  7161.                          in sequence, i.e., 1, 2, 3, etc.  If NO keys are
  7162.                          specified, the file will be RANDOM. 
  7163.  
  7164.                          When the screen is first displayed, key number 1 will
  7165.                          be displayed.  Put in the keys by FID file name using
  7166.                          the TAB to go from field to field. 
  7167.  
  7168.                          In each space enter the name of the FID file field that
  7169.                          comprises the key.  Note: A file with no keys is a
  7170.                          random file.  See the programmer's reference manual for
  7171.                          more information on random files.
  7172.  
  7173.  
  7174.                                              Notes on keys
  7175.                                              -------------
  7176.                          Definitions
  7177.                          -----------
  7178.  
  7179.                          A key is an ASCII string consisting of one or more
  7180.                          fields that need not be adjacent.  A file may have up
  7181.                          to 9 keys.  Key 1 is, by convention, the <BI>primary
  7182.                          key.  All other keys are referred to as <BI>secondary
  7183.                          keys.
  7184.  
  7185.  
  7186.                               Binary WorkStation Editor
  7187.                                        Page 106
  7188.  
  7189.  
  7190.  
  7191.  
  7192.  
  7193.  
  7194.  
  7195.  
  7196.                          Primary Keys are UNIQUE.  There are NO duplicates.  In
  7197.                          other words, there is one and only one record with this
  7198.                          key.
  7199.  
  7200.                          Secondary Keys may be duplicated.  You may have many
  7201.                          records with the same secondary key.     
  7202.  
  7203.                          Use -- A file can be positioned to a specific record if
  7204.                          the value of the record's primary key is known.  It can
  7205.                          be positioned to the first record of a set that has the
  7206.                          same secondary key.
  7207.       
  7208.                          Character Alignment -- Because the keys are ASCII
  7209.                          strings, you must be careful of the alignment of the
  7210.                          fields and, particularly with numeric keys, leading
  7211.                          characters.
  7212.  
  7213.                          Generally, alphanumeric fields used as keys will be
  7214.                          left justified.
  7215.  
  7216.                          If you want the records to be in sequence with numeric
  7217.                          keys, they must be right justified.  Remember, left
  7218.                          zero (0) fill is not the same as left blank fill.   
  7219.  
  7220.  
  7221.      F8 - Align Fields with other Fields
  7222.           Brings up this screen:
  7223.  
  7224.                 Field name     Offset   Aligned with
  7225.                [         ]     [    ]   [         ]
  7226.                [         ]     [    ]   [         ]
  7227.           .
  7228.           .
  7229.           .
  7230.                [         ]     [    ]   [         ]
  7231.  
  7232.           Aligned with   This field contains the name of a previous field within
  7233.                          this record with the same starting character position
  7234.                          as the current field.  If left blank, then the current
  7235.                          field takes the next available character position.  If
  7236.                          not blank, then it must contain the name of such a
  7237.                          field.  All later field definitions will be located
  7238.                          after this field.
  7239.  
  7240.                          Using this facility, data files may effectively have
  7241.                          more than one record format, either by redefining the
  7242.                          entire record, or by leaving the first section of the
  7243.                          record common to all formats.  For example, if we
  7244.  
  7245.  
  7246.                               Binary WorkStation Editor
  7247.                                        Page 107
  7248.  
  7249.  
  7250.  
  7251.  
  7252.  
  7253.  
  7254.  
  7255.                          wished to store invoices and invoice payments within
  7256.                          the same file, we could have the following (simplified)
  7257.                          sequence of fields:
  7258.  
  7259.           NAME      LEN  LOCATION       DESCRIPTION
  7260.           ----      ---  --------       ------------
  7261.           INVNUM    6         1         Invoice #
  7262.           TYPE      2         7         Blank if invoice, else payment number
  7263.           SHIPPER   20        9         Shipper name
  7264.           PRODNO    4         29        Product number
  7265.           QUAN      4         33        # of items shipped
  7266.           PRICE     7         37        Price each
  7267.  
  7268.      (This much defines an invoice.  Now for the fields which redefine the same
  7269.      record space for a payment entry).
  7270.  
  7271.           CHECK     6         9         Check # (aligned with SHIPPER).
  7272.           MONTH     2         15        Month of check date.
  7273.           DAY       2         17        Day of check date.
  7274.           YEAR      2         19        Year of check date.
  7275.           AMT       7         21        Month of check.
  7276.  
  7277.      In referencing this as file 1, if &TYPE[1] was non-zero, then the record
  7278.      represents a payment; that is, &CHECK[1], &MONTH[1], &DAY[1], and &AMT[1]
  7279.      represent valid data.  If &TYPE[1] is zero, then we should only deal with
  7280.      &SHIPPER[1], &PRODNO[1], &QUAN[1], and &PRICE[1], since this is an invoice
  7281.      record.
  7282.  
  7283.      Refer to sample programs and FIDS for examples of the use of aligned
  7284.      fields.
  7285.  
  7286.      F9 - Merge FID file This selection allows merging into the currently
  7287.                          displayed FID file another FID file.  You can use it to
  7288.                          make a FID for multiple screens by using the Quick FID
  7289.                          option an then the merge.  Pressing F9 will move the
  7290.                          cursor to the top of the FID screen with this message:
  7291.  
  7292.                          MERGE FILE ___________________
  7293.  
  7294.                          Enter the name of the FID file to be merged and press
  7295.                          ENTER. 
  7296.  
  7297.      Sh-F10 - Quit       Exit the FID generator.
  7298.  
  7299.      Sh-F1 - Print       Print the FID definition.
  7300.  
  7301.      Sh-F2 - Quick FID   This selection creates a FID file from an application
  7302.                          file.  All the screen data fields and their definitions
  7303.                          will be in the created FID file.  The default key will
  7304.  
  7305.  
  7306.                               Binary WorkStation Editor
  7307.                                        Page 108
  7308.  
  7309.  
  7310.  
  7311.  
  7312.  
  7313.  
  7314.  
  7315.                          be the first screen data field on the screen.  
  7316.  
  7317.                          Once the name is entered and the FID file updated from
  7318.                          the main menu, any previously generated FID with the
  7319.                          same file name will be over written with the new FID. 
  7320.                          You may modify the created FID in the same manner as
  7321.                          any other.
  7322.  
  7323.      X - Return to Main Menu
  7324.                          Returns to the main menu screen.
  7325.  
  7326.  
  7327.                              Referencing File Data Fields
  7328.                              ----------------------------
  7329.  
  7330.                                  Referencing By Name
  7331.                                  -------------------
  7332.      Fields in records described by FID files may be referenced by name like any
  7333.      other data item (variables, screen fields, registers, etc.). The syntax of
  7334.      a FID field reference is as follows:
  7335.  
  7336.           &name [file# {,array element}]
  7337.  
  7338.                &name          file field name
  7339.                file #         the file number referenced.
  7340.                array element  the number of the file field repetition, beginning
  7341.                               with 0 (zero).
  7342.  
  7343.           Remarks
  7344.           -------
  7345.           Since FID fields may have the same name in different files, or as
  7346.           screen fields or variables, the "&" denotes that a FID field is being
  7347.           referenced.  The file number may be any arithmetic expression
  7348.           resulting in the desired number. 
  7349.  
  7350.                Examples:
  7351.  
  7352.                &LASTNAME[1]        The field LASTNAME from file 1
  7353.                &LASTNAME[#N2]      The field LASTNAME from the file whose file
  7354.                                    number is in #N2.  
  7355.       
  7356.           The index is used only for FID field arrays, that is, FID fields that
  7357.           are defined with more than one repetition.  The index denotes which
  7358.           item in the FID field array is desired.  The first FID field in the
  7359.           array has an element number of zero.  Indices may range from 0 to the
  7360.           number of elements minus 1.  If no index is given for a replicated
  7361.           item, 1 is assumed.
  7362.  
  7363.                Examples:
  7364.  
  7365.  
  7366.                               Binary WorkStation Editor
  7367.                                        Page 109
  7368.  
  7369.  
  7370.  
  7371.  
  7372.  
  7373.  
  7374.  
  7375.  
  7376.                &NUMBER(1,3)        The fourth element in the file array NUMBER. 
  7377.  
  7378.                &NUMBER(#N1, #N2)   The element number contained in #N2 in file
  7379.                                    number #N1.
  7380.  
  7381.  
  7382.  
  7383.  
  7384.  
  7385.  
  7386.  
  7387.  
  7388.  
  7389.  
  7390.  
  7391.  
  7392.  
  7393.  
  7394.  
  7395.  
  7396.  
  7397.  
  7398.  
  7399.  
  7400.  
  7401.  
  7402.  
  7403.  
  7404.  
  7405.  
  7406.  
  7407.  
  7408.  
  7409.  
  7410.  
  7411.  
  7412.  
  7413.  
  7414.  
  7415.  
  7416.  
  7417.  
  7418.  
  7419.  
  7420.  
  7421.  
  7422.  
  7423.  
  7424.  
  7425.  
  7426.                               Binary WorkStation Editor
  7427.                                        Page 110
  7428.  
  7429.  
  7430.  
  7431.  
  7432.  
  7433.  
  7434.  
  7435.                                   Q - PRO 4 Commands
  7436.  
  7437.  
  7438.                             Q - P R O 4   C O M M A N D S
  7439.                             =============================
  7440.  
  7441.                                       Symbology
  7442.                                       =========
  7443.  
  7444.      Several symbols have been chosen as delimiters of portions of the commands. 
  7445.      They are:
  7446.  
  7447.      Curly Braces ({})        Enclose an optional phrase as explained in the
  7448.                               text.  The vertical lines are never part of the
  7449.                               command.
  7450.      Angle Brackets (<>)      Enclose phrases that are generic symbols.  The
  7451.                               angle brackets are never part of the command.
  7452.      Square Brackets ([ ])    Used in various contexts as actual parts of a
  7453.                               command. 
  7454.      Parentheses (( ))        Used interchangeably with square brackets and in
  7455.                               expressions in various contexts as parts of a
  7456.                               command.
  7457.  
  7458.      Structure of the Commands
  7459.      -------------------------
  7460.      A command is made up of the following elements:
  7461.  
  7462.      Label (Optional)    A numeric line number or an alphanumeric label.  An
  7463.                          alphabetic label is denoted by a leading colon (:).
  7464.      Statement           The executable statement, broken into:
  7465.  
  7466.                          VERB - The main command
  7467.                          OPERANDS - Data items
  7468.                          MODIFIERS - Additional operations for the 
  7469.                          verb
  7470.  
  7471.      Error               Line number or label to branch to on error.
  7472.  
  7473.           Example: 
  7474.           :FIND_IT   TSEAR TABLE AT #N1, #S1: NO_GOT
  7475.  
  7476.         Where:
  7477.  
  7478.                :FIND_IT  is the label
  7479.                TSEAR     is the verb
  7480.                #N1, #S1  are data items
  7481.                TABLE     is a modifier
  7482.                AT        is a modifier
  7483.                          separator for error branch
  7484.  
  7485.  
  7486.                                        Commands
  7487.                                        Page 111
  7488.  
  7489.  
  7490.  
  7491.  
  7492.  
  7493.  
  7494.  
  7495.                                   Q - PRO 4 Commands
  7496.  
  7497.  
  7498.           NO_GOT    label to branch to
  7499.      Naming Conventions
  7500.      ------------------
  7501.      Names within Q-PRO 4 follow the conventions listed below.  These
  7502.      conventions apply to screen field names, file field names, variables, and
  7503.      labels.
  7504.  
  7505.           1.   The first character of any name must be an alphabetic character.
  7506.           2.   The name may be up to 10 alphanumeric characters long.
  7507.           3.   Underline characters (_) may be embedded in the name for clarity
  7508.                and they are counted in the 10 character length.
  7509.  
  7510.           Examples:
  7511.  
  7512.                FIELD_NAME     CUST_FILE      DATA ITEMS
  7513.  
  7514.  
  7515.      Data Items
  7516.      ----------
  7517.      There are six different classifications of data items as shown below.  Each
  7518.      classification is of one or more types:  string, numeric, and Boolean.  In
  7519.      the table below, these types are represented as shown:
  7520.  
  7521.      N is Numeric (0-9, decimal point, sign)
  7522.      S is String (all alphanumerics)
  7523.      B is Boolean or bit (a bit set or reset)
  7524.  
  7525.       
  7526.               DATA ITEM            TYPE
  7527.  
  7528.           1.  Data registers       N, S
  7529.           2.  Special Registers    N, B
  7530.           3.  Screen data fields   N, S 
  7531.           4.  Literals             N, S
  7532.           5.  Variables            N, S
  7533.           6.  File data fields     N, S
  7534.  
  7535.      1.  Data Registers
  7536.      ------------------
  7537.           #N0-#N9   Numeric registers   Numeric registers may only contain
  7538.                                         numeric data (0-9 decimal point and a
  7539.                                         leading minus sign).
  7540.           #S0-#S9   String registers    String registers may contain a string of
  7541.                                         up to 255 characters.  
  7542.  
  7543.  
  7544.  
  7545.  
  7546.                                        Commands
  7547.                                        Page 112
  7548.  
  7549.  
  7550.  
  7551.  
  7552.  
  7553.  
  7554.  
  7555.                                   Q - PRO 4 Commands
  7556.  
  7557.  
  7558.  
  7559.  
  7560.      2.  Special Registers
  7561.      ---------------------
  7562.           #B0-#B9        The Boolean or flag registers. 
  7563.           #E             The error register.
  7564.           #F             A read-only numeric register which contains the current
  7565.                          screen field number.
  7566.           #K             The keyout register.  The values for this register are
  7567.                          as follows:
  7568.                        Value  Meaning
  7569.                         ---   ------- 
  7570.                          0    typed out
  7571.                          1    tabbed out
  7572.                          2    backtabbed out
  7573.                          3    cursor up 
  7574.                          4    cursor down, newline     
  7575.                          5    cursor left 
  7576.                          6    cursor right
  7577.                          7    enter 
  7578.                          8    home
  7579.                          9    any function key
  7580.                         10    break
  7581.  
  7582.           #L             The line counter register.
  7583.           #P             The page number register.
  7584.  
  7585.      3.  Screen Data Fields
  7586.      ----------------------
  7587.      Screen fields are defined by the programmer.  They may be manipulated in
  7588.      any way. 
  7589.  
  7590.      4. Literals
  7591.      -----------
  7592.      Literals (constant values) may be numeric, string or control character .
  7593.           String literal examples:  "THIS IS A STRING LITERAL"
  7594.                                     'A string literal with single quotes'
  7595.           Numeric literal examples: 19746    289567
  7596.           Control character literal examples: @44   @158  @(#N0 + 5)
  7597.  
  7598.      5. Variables 
  7599.      ------------
  7600.      Variables are data items, maintained in memory.  They may take on single
  7601.      values (in which case they are referenced directly by name), or multiple
  7602.      values (in which case we call them ARRAYS, and reference them with an
  7603.      indexing expression which names the specific element of the array we desire
  7604.  
  7605.  
  7606.                                        Commands
  7607.                                        Page 113
  7608.  
  7609.  
  7610.  
  7611.  
  7612.  
  7613.  
  7614.  
  7615.                                   Q - PRO 4 Commands
  7616.  
  7617.  
  7618.      to access).
  7619.  
  7620.      6. File Data Fields
  7621.      -------------------
  7622.      Fields in data records may be accessed in two ways, either by their
  7623.      relative positions within the record, or by their names.  The second way is
  7624.      accomplished by associating a FID (field item descriptor) file with a data
  7625.      file.  Syntax:
  7626.  
  7627.           &FIELD NAME [<FILE NUMBER> {, <INDEX>}
  7628.  
  7629.      The ampersand (&) in front of the field name tells Q-PRO 4 that this is a
  7630.      file field name.  The <FIELD NAME> tells the system where on the record the
  7631.      data is located.  The <FILE NUMBER> tells the system which file is to be
  7632.      used (since different files may have the same field names).  The optional
  7633.      index selects one element from a field array when appropriate.  Example:  
  7634.  
  7635.           &CUSTNAME[1,2]
  7636.  
  7637.      Expressions
  7638.      -----------
  7639.      An expression is a set of numeric data items joined by mathematical
  7640.      operators which Q-PRO 4 will evaluate into a number.  Many of the Q-PRO 4
  7641.      commands may use expressions.  This allows the programmer to let the
  7642.      program calculate complex relationships.
  7643.  
  7644.      For example, a particular element in an array is desired at a given time is
  7645.      5 or ARRAY[5], and at another time, it may be 6, etc.  This element may be
  7646.      calculated in an expression such that it is dynamically set instead of
  7647.      explicitly set by ARRAY[expression].  The expression is any set of numeric
  7648.      data items such as:
  7649.           
  7650.           #N1 + (#N2 * 3)
  7651.           ARRAY[#N1 + 2]
  7652.           ARRAY[#N1+(#N2 * #N3)]
  7653.           ARRAY[ARRAY[#N3]]
  7654.  
  7655.           Examples: MOVE ARRAY1[#N1 + #N2 + 3] TO ARRAY2[#N1-#N2]
  7656.                     ADD ARRAY1[#N1 + (#N2 + 3)] TO $FIELD[#F + #N1]
  7657.  
  7658.  
  7659.  
  7660.  
  7661.  
  7662.  
  7663.  
  7664.  
  7665.  
  7666.                                        Commands
  7667.                                        Page 114
  7668.  
  7669.  
  7670.  
  7671.  
  7672.  
  7673.  
  7674.  
  7675.                                   Q - PRO 4 Commands
  7676.  
  7677.  
  7678.                                    Function Summary
  7679.                                    ================
  7680.       
  7681.      $ASC(data item)     Returns the decimal for the ASCII data item 
  7682.      $ETOX(data item)    Returns e raised to the data item power
  7683.      $FIELD(data item)   Returns the screen data field value given an offset
  7684.      $INT(data item)     Returns the integer
  7685.      $LN(data item)      Returns the natural log
  7686.      $MEMEND()           Returns the top of memory
  7687.      $OFFSET(fieldname)  Returns the offset of the named field
  7688.       
  7689.  
  7690.  
  7691.  
  7692.  
  7693.  
  7694.  
  7695.  
  7696.  
  7697.  
  7698.  
  7699.  
  7700.  
  7701.  
  7702.  
  7703.  
  7704.  
  7705.  
  7706.  
  7707.  
  7708.  
  7709.  
  7710.  
  7711.  
  7712.  
  7713.  
  7714.  
  7715.  
  7716.  
  7717.  
  7718.  
  7719.  
  7720.  
  7721.  
  7722.  
  7723.  
  7724.  
  7725.  
  7726.                                        Commands
  7727.                                        Page 115
  7728.  
  7729.  
  7730.  
  7731.  
  7732.  
  7733.  
  7734.  
  7735.                                   Q - PRO 4 Commands
  7736.  
  7737.  
  7738.                                    Command Summary
  7739.                                    ===============
  7740.  
  7741.  
  7742.      ACCURACY       Sets the number of decimal places of accuracy.
  7743.      ADD            Adds two numeric data items together.
  7744.      ASEAR          Searches a memory array.
  7745.      BACKSPACE      Backspaces the file one record.
  7746.      BEGIN          Denotes the beginning of the structured construct.  
  7747.      BELL           Causes the audible alarm to sound.
  7748.      BUFFER         Changes the size of the keyboard keying buffer.
  7749.      BROFF          Disables PROC BREAK (if any).
  7750.      BRON           Enables PROC BREAK (if any).
  7751.      CALC           Calculates the value of an expression.
  7752.      CALL           Calls a subroutine.
  7753.      CENTER         Centers data in a string data item.
  7754.      CHAIN          Loads and executes another Q-PRO 4 program.
  7755.      CLEAR          Clears a data entry field.
  7756.      CLOSE          Closes a data file.
  7757.      CONCAT         Concatenates a set of string data items into one string data
  7758.                     item.
  7759.      CURSOR         Positions the cursor independently of the displayed form and
  7760.                     its fields.
  7761.      CURRENCY       Changes the currency symbol used in EDIT.
  7762.      DEBUG          For program debugging. 
  7763.      DEFSEG         For 16 bit versions for PEEK, POKE and DEBUG.
  7764.      DIV            Divides one data item by another.
  7765.      EDIT           Formats numeric data items according to a picture of the
  7766.                     desired result.
  7767.      ELSE           Alternate branch for a structured function.
  7768.      END            Marks the end of a procedure or table.
  7769.      ENDBEGIN       Denotes the end of a structured function. 
  7770.      ENDFOR         Terminate a FOR loop.
  7771.      ERASE          Removes a file from a diskette.
  7772.      ERROR          Displays error message on the bottom of the screen.
  7773.      ERRTRAP        Sets a label as an error branch, or clears such a label if
  7774.                     an error branch was previously set.
  7775.      EXEC           Runs a machine code routine. 
  7776.      FCOPY          Copies a file. 
  7777.      FILETYPE       Returns information about an open file.
  7778.      FILL           Makes field fill in unlocked screen fields any character
  7779.                     desired.
  7780.      FOR            Marks the beginning of a loop.       
  7781.      FORMLOAD       Returns control to FB on fatal error or returning to system.
  7782.      FREE           Deletes a record from an indexed file.
  7783.      FSEAR          Searches a data file on a record-by-record basis for of any
  7784.  
  7785.  
  7786.                                        Commands
  7787.                                        Page 116
  7788.  
  7789.  
  7790.  
  7791.  
  7792.  
  7793.  
  7794.  
  7795.                                   Q - PRO 4 Commands
  7796.  
  7797.  
  7798.                     logical condition.
  7799.      GET            Moves a data field from a file buffer.
  7800.      GETDATE        Loads the current system date.
  7801.      GOTO           Immediate jump to label or line number.
  7802.      HELP           Displays help screens created by the programmer.
  7803.      HOFF           Turns highlights off at the cursor position.
  7804.      HON            Turns the screen highlight on at cursor position.
  7805.      HOME           Homes the cursor.
  7806.      HOMECLEAR      Homes the cursor and clears all enterable fields.
  7807.      HOST           Establishes the host operating system. 
  7808.      IF             Conditionally executes program statements.
  7809.      INSTR          Searches a string for a substring.
  7810.      JDPACK         Calculates a Julian date and moves it into a data item.
  7811.      JDUNPACK       Converts the previously created Julian date in a data item
  7812.                     to a calendar date.
  7813.      LJUST          Left justifies data.
  7814.      KEY            Changes the file current KEY.  
  7815.      LOAD           Loads a machine code file into memory.
  7816.      LOCK           Makes an enterable screen data field not enterable.
  7817.      LPDETACH       Detaches the process from the system printer.
  7818.      LRETRY         Sets the retry count for header locking on LANs.
  7819.      MAKE           Creates a data file.
  7820.      MEMEND         Sets the high address in memory for QNE can use, normally
  7821.                     for use of machine language programs
  7822.      MOVE           Transfers data between data items.
  7823.      MUL            Multiplies two data items.
  7824.      NCHECK         Verifies that a string data item contains valid numeric
  7825.                     data.
  7826.      NEXT           Moves the cursor to a specified screen field.
  7827.      NOFORMLOAD     Resets indicator set by the FORMLOAD command.
  7828.      NOTRACE        Turns off TRACE mode.
  7829.      OPEN           Locates file on disk and readies it for I/O operations.
  7830.      PEEK           Loads data into a string from memory.
  7831.      POKE           Moves a string of data into memory. 
  7832.      POSN           Positions a random or indexed file to a record.
  7833.      PRINT          Prints directly to the screen.
  7834.      PRINTSCN       Dumps the screen to the list device.
  7835.      PROC           Denotes the start of a procedure.
  7836.      PUT            Transfers data to a file buffer or printer.
  7837.      RCLEAR         Clears the record buffer, resets the pointer.  
  7838.      READ           Used to access data records within a file.
  7839.      RENAME         Changes the name of a file.
  7840.      RESET          Clears a Boolean flag register. 
  7841.      RESTART        Resets the file buffer or performs a form feed.
  7842.      RESUME         Return control to the operator for data entry.
  7843.      RETURN         Returns control to a CALL PROC. 
  7844.  
  7845.  
  7846.                                        Commands
  7847.                                        Page 117
  7848.  
  7849.  
  7850.  
  7851.  
  7852.  
  7853.  
  7854.  
  7855.                                   Q - PRO 4 Commands
  7856.  
  7857.  
  7858.      RJUST          Right justifies data.
  7859.      RLOCK          Locks the currently positioned record in the file. 
  7860.      ROUND          Rounds a numeric quantity to some significant number of
  7861.                     digits.
  7862.      RUN            Executes another program directly from Q-PRO 4.
  7863.      RUNLOCK        Unlocks the currently locked record in the file.
  7864.      SECURE         Forces the update of an indexed file.
  7865.      SET            Sets a Boolean flag register.
  7866.      SETDATE        Sets the system date.
  7867.      SIZE           Computes the length of a string data item.
  7868.      SUB            Subtracts one data item from another.
  7869.      SYSMODE        General system command to change characteristic of backtab
  7870.                     and printer detection errors.
  7871.      SYSTEM         Gives control back to the operating system. 
  7872.      TABLE          Denotes the start of a data table.
  7873.      TRACE          Places Q-PRO 4 in a single step debugging mode.
  7874.      TSEAR          Initiates the search of a table.
  7875.      UCASE          Forces a string data item to upper case.
  7876.      UNEDIT         Removes editing characters from a string field.
  7877.      UNLOCK         Unlocks a previously locked field.
  7878.      VRBL           Establishes in-memory variables.
  7879.      WRITE          Outputs a data record to a file.
  7880.  
  7881.  
  7882.  
  7883.  
  7884.  
  7885.  
  7886.  
  7887.  
  7888.  
  7889.  
  7890.  
  7891.  
  7892.  
  7893.  
  7894.  
  7895.  
  7896.  
  7897.  
  7898.  
  7899.  
  7900.  
  7901.  
  7902.  
  7903.  
  7904.  
  7905.  
  7906.                                        Commands
  7907.                                        Page 118
  7908.  
  7909.  
  7910.  
  7911.  
  7912.  
  7913.  
  7914.  
  7915.                                   Q - PRO 4 Commands
  7916.  
  7917.  
  7918.                                   F u n c t i o n s
  7919.                                   =================
  7920.  
  7921.      $ASC
  7922.      ----
  7923.      The function $ASC returns the decimal value of the ASCII data item.
  7924.  
  7925.      Syntax: $ASC(<ASCII data item>)
  7926.  
  7927.      ASCII data item     A literal in quotes, a string register or string
  7928.                          variable.
  7929.  
  7930.      Examples:      $ASC("3")      returns 51
  7931.                     $ASC("A")      returns 65
  7932.  
  7933.  
  7934.  
  7935.  
  7936.  
  7937.  
  7938.  
  7939.  
  7940.  
  7941.  
  7942.  
  7943.  
  7944.  
  7945.  
  7946.  
  7947.  
  7948.  
  7949.  
  7950.  
  7951.  
  7952.  
  7953.  
  7954.  
  7955.  
  7956.  
  7957.  
  7958.  
  7959.  
  7960.  
  7961.  
  7962.  
  7963.  
  7964.  
  7965.  
  7966.                                        Commands
  7967.                                        Page 119
  7968.  
  7969.  
  7970.  
  7971.  
  7972.  
  7973.  
  7974.  
  7975.                                   Q - PRO 4 Commands
  7976.  
  7977.  
  7978.      $ETOX
  7979.      -----
  7980.      The $ETOX function returns the value of the natural constant e raised to
  7981.      the expression power.  On 8 bit systems, MATHLIB must be loaded.  (The
  7982.      MATHLIB command is ignored on other systems.)
  7983.  
  7984.      Syntax:   $ETOX(<expression>)
  7985.  
  7986.      expression     An evaluatable mathematical expression.
  7987.  
  7988.      Examples:      CALC EPOWER = $ETOX(#N1)
  7989.                     CALC COMPLEX = $ETOX((#N1 + #N2}2) -1)
  7990.  
  7991.  
  7992.  
  7993.  
  7994.  
  7995.  
  7996.  
  7997.  
  7998.  
  7999.  
  8000.  
  8001.  
  8002.  
  8003.  
  8004.  
  8005.  
  8006.  
  8007.  
  8008.  
  8009.  
  8010.  
  8011.  
  8012.  
  8013.  
  8014.  
  8015.  
  8016.  
  8017.  
  8018.  
  8019.  
  8020.  
  8021.  
  8022.  
  8023.  
  8024.  
  8025.  
  8026.                                        Commands
  8027.                                        Page 120
  8028.  
  8029.  
  8030.  
  8031.  
  8032.  
  8033.  
  8034.  
  8035.                                   Q - PRO 4 Commands
  8036.  
  8037.  
  8038.      $FIELD
  8039.      ------
  8040.      $FIELD is a function that returns the screen data field that corresponds to
  8041.      the offset value.  Its parameter is the number of the field to be
  8042.      addressed.  Using this function, the programmer may dynamically address and
  8043.      manipulate data in screen data fields symbolically instead of by name. 
  8044.      Refer to the Programmer's Reference Manual and sample programs for more
  8045.      detail and examples.
  8046.  
  8047.      Syntax:   $FIELD(<expression>)
  8048.  
  8049.      expression     Any mathematical expression that evaluates to an integer
  8050.                     without sign.
  8051.  
  8052.      Examples:      ADD $FIELD[#N1] TO SUM
  8053.                          Add the screen data field with the offset contained in
  8054.                          the numeric register #N1 to the screen data field (or
  8055.                          variable) SUM.
  8056.  
  8057.                     MOVE &FILE_FIELD[1,#N1] TO $FIELD[#N1 + (#N1 * 6)]
  8058.                          Move the #N1 element of the file data array FILE_FIELD
  8059.                          on file 1 to the screen data field whose offset is the
  8060.                          evaluation of the expression [#N1 + (#N1 * 6)].
  8061.  
  8062.  
  8063.  
  8064.  
  8065.  
  8066.  
  8067.  
  8068.  
  8069.  
  8070.  
  8071.  
  8072.  
  8073.  
  8074.  
  8075.  
  8076.  
  8077.  
  8078.  
  8079.  
  8080.  
  8081.  
  8082.  
  8083.  
  8084.  
  8085.  
  8086.                                        Commands
  8087.                                        Page 121
  8088.  
  8089.  
  8090.  
  8091.  
  8092.  
  8093.  
  8094.  
  8095.                                   Q - PRO 4 Commands
  8096.  
  8097.  
  8098.      $INT
  8099.      ----
  8100.      $INT is a function that returns the integer portion of a real number.  
  8101.  
  8102.      Syntax:   $INT(<numeric data item>)  
  8103.           
  8104.      numeric data item   A literal number (without quotes), numeric register,
  8105.                          numeric variable, or numeric screen data field. 
  8106.  
  8107.      Examples:      CALC #N1 =#N1 + $INT(#N2)
  8108.                          CALCulates and places in #N1 the current value of #N1
  8109.                          plus the integer portion of #N2.
  8110.  
  8111.                     CALC #N1 =$INT(5.05)
  8112.                          Result in #N1 is 5.
  8113.  
  8114.                     CALC #N1 =#N2-#N2 * $INT(#N2}#N1) 
  8115.                          The result in #N1 is modulo #n1.
  8116.  
  8117.  
  8118.  
  8119.  
  8120.  
  8121.  
  8122.  
  8123.  
  8124.  
  8125.  
  8126.  
  8127.  
  8128.  
  8129.  
  8130.  
  8131.  
  8132.  
  8133.  
  8134.  
  8135.  
  8136.  
  8137.  
  8138.  
  8139.  
  8140.  
  8141.  
  8142.  
  8143.  
  8144.  
  8145.  
  8146.                                        Commands
  8147.                                        Page 122
  8148.  
  8149.  
  8150.  
  8151.  
  8152.  
  8153.  
  8154.  
  8155.                                   Q - PRO 4 Commands
  8156.  
  8157.  
  8158.      $LN
  8159.      ---
  8160.      $LN is a function that returns the natural logarithm of the included
  8161.      expression.  $LN may be used in conjunction with ACCURACY to limit the
  8162.      accuracy and decrease the execution time.
  8163.  
  8164.      Syntax:   $LN(<expression>)
  8165.  
  8166.      expression     A mathematically evaluatable set of terms and operators.
  8167.  
  8168.      Example:       CALC COMPLEX = $LN((#N1 + #N2)  * #N3)
  8169.  
  8170.      $MEMEND()
  8171.      ---------
  8172.      The $MEMEND() function returns the current top of memory being used by
  8173.      Q-PRO 4, its file buffers and keypool.  Some of this memory, particularly
  8174.      in the keypool area can be used by the programmer for assembly language
  8175.      routines without impacting Q-PRO 4 or the remainder of memory.  When Q-PRO
  8176.      4 is loaded, the memory is laid out like this:
  8177.  
  8178.      |-----Top of memory-----------|
  8179.      |                             |
  8180.      |  This area is available     |
  8181.      |                             |
  8182.      |                             |
  8183.      |-298K (All that can be used)-|
  8184.      |                             |
  8185.      |                             | 
  8186.      |Q-PRO 4 Data area, up to 64K |
  8187.      |                             |
  8188.      |-----------------------------|
  8189.      |                             |
  8190.      | Application area, up to 64K |
  8191.      |                             |
  8192.      |-----------------------------|
  8193.      |                             |
  8194.      | Runtime Interpreter - 42K   |
  8195.      |                             |
  8196.      |-----------------------------|
  8197.      |                             |
  8198.      |    BTSYS - the file system  |
  8199.      |     (requires 100K)         |
  8200.      |-----------------------------|
  8201.      |    Operating System         |
  8202.      |                             |
  8203.      |------Bottom of Memory-------|
  8204.  
  8205.  
  8206.                                        Commands
  8207.                                        Page 123
  8208.  
  8209.  
  8210.  
  8211.  
  8212.  
  8213.  
  8214.  
  8215.                                   Q - PRO 4 Commands
  8216.  
  8217.  
  8218.      The command:
  8219.  
  8220.      MEMEND $MEMEND() - 1024
  8221.  
  8222.      produces this result
  8223.  
  8224.      |-----Top of memory-----------|
  8225.      |                             |
  8226.      |  1024 bytes available for   |
  8227.      |   assembly language program |
  8228.      |-----------------------------|
  8229.      |  Memory available for key   |
  8230.      |  pool.                      |
  8231.      |-----------------------------| 
  8232.      |Q-PRO 4 Data area, up to 64K |
  8233.      |                             |
  8234.      |-----------------------------|
  8235.      |                             |
  8236.      | Application area, up to 64K |
  8237.      |                             |
  8238.      |-----------------------------|
  8239.      |                             |
  8240.      | Runtime Interpreter - 42K   |
  8241.      |                             |
  8242.      |-----------------------------|
  8243.      |                             |
  8244.      |    BTSYS - the file system  |
  8245.      |     (requires 100K)         |
  8246.      |-----------------------------|
  8247.      |    Operating System         |
  8248.      |                             |
  8249.      |------Bottom of Memory-------|
  8250.  
  8251.      Use the MA command in DEBUG to find out the keypool size so you can
  8252.      determine exactly how much memory the program requires.
  8253.  
  8254.  
  8255.  
  8256.  
  8257.  
  8258.  
  8259.  
  8260.  
  8261.  
  8262.  
  8263.  
  8264.  
  8265.  
  8266.                                        Commands
  8267.                                        Page 124
  8268.  
  8269.  
  8270.  
  8271.  
  8272.  
  8273.  
  8274.  
  8275.                                   Q - PRO 4 Commands
  8276.  
  8277.  
  8278.      $OFFSET
  8279.      -------
  8280.      The function $OFFSET returns the offset of the named screen data field. 
  8281.      Use of this function allows generalized code for symbolic screen data
  8282.      manipulation relative to screen data fields.
  8283.  
  8284.      Syntax:   OFFSET<screen data field name>
  8285.  
  8286.      screen data field name   The name of the screen data field in quotes.
  8287.  
  8288.      Examples:           CALC #N1 = $OFFSET("DATE")
  8289.                               #N1 will contain the offset of the screen data
  8290.                               field DATE.
  8291.  
  8292.           Note that:  $OFFSET($FIELD[#F]) = #F     
  8293.       
  8294.  
  8295.  
  8296.  
  8297.  
  8298.  
  8299.  
  8300.  
  8301.  
  8302.  
  8303.  
  8304.  
  8305.  
  8306.  
  8307.  
  8308.  
  8309.  
  8310.  
  8311.  
  8312.  
  8313.  
  8314.  
  8315.  
  8316.  
  8317.  
  8318.  
  8319.  
  8320.  
  8321.  
  8322.  
  8323.  
  8324.  
  8325.  
  8326.                                        Commands
  8327.                                        Page 125
  8328.  
  8329.  
  8330.  
  8331.  
  8332.  
  8333.  
  8334.  
  8335.                                   Q - PRO 4 Commands
  8336.  
  8337.  
  8338.                                    C O M M A N D S
  8339.                                    ===============
  8340.  
  8341.      ACCURACY
  8342.      --------
  8343.      ACCURACY is used with ETOX, exponentiation and LN to set the degree of
  8344.      accuracy that the calculations will be carried out.  As all of these
  8345.      routines are mathematically converging functions, by using this command,
  8346.      execution will take only as long as required for the computation.
  8347.  
  8348.      Syntax:   ACCURACY(<numeric data item>)
  8349.  
  8350.      numeric data item   Any expression that evaluates to a whole number between
  8351.                          1 and 7.  
  8352.      Remarks             The default is 7.
  8353.  
  8354.      Examples:
  8355.                ACCURACY(#n1)
  8356.                ACCURACY(3)
  8357.        
  8358.  
  8359.  
  8360.  
  8361.  
  8362.  
  8363.  
  8364.  
  8365.  
  8366.  
  8367.  
  8368.  
  8369.  
  8370.  
  8371.  
  8372.  
  8373.  
  8374.  
  8375.  
  8376.  
  8377.  
  8378.  
  8379.  
  8380.  
  8381.  
  8382.  
  8383.  
  8384.  
  8385.  
  8386.                                        Commands
  8387.                                        Page 126
  8388.  
  8389.  
  8390.  
  8391.  
  8392.  
  8393.  
  8394.  
  8395.                                   Q - PRO 4 Commands
  8396.  
  8397.  
  8398.      ADD
  8399.      ---
  8400.      The ADD command adds two numeric data items together and optionally places
  8401.      the result in a third numeric data item.  Optionally, the data items may be
  8402.      preceded by minus sign (-).  The results of an add (or any arithmetic
  8403.      operation) may not be stored in a numeric constant.  The receiving data
  8404.      item must be a numeric data item.  For example, ADD FLD1 TO 3 is invalid.
  8405.  
  8406.      Syntax:
  8407.  
  8408.      ADD <data item 1> TO <data item 2>{GIVING <data items><B>}
  8409.  
  8410.      data item 1    A numeric data item such as a literal or numeric register. 
  8411.                     An expression is not allowed.
  8412.  
  8413.      data item 2    A numeric data item.  An expression is not allowed.  If the
  8414.                     GIVING modifier is not present, the sum of data item 1 and
  8415.                     data item 2 will be stored in data item 2 and data item two
  8416.                     must not be a literal.  
  8417.  
  8418.      data item 3    If present, the sum will be placed in this item.  Therefore,
  8419.                     it must not be a variable.
  8420.  
  8421.      Remarks        GIVING is optional serving the purpose of defining a third
  8422.                     data item in which to place the sum.  The keyword TO may be
  8423.                     replaced by a comma.
  8424.  
  8425.      Examples:
  8426.           ADD #N3 TO SUM
  8427.           ADD .5, NUMB GIVING #N1
  8428.           ADD 3 TO FLD1
  8429.           ADD FLD1 TO 3 GIVING FLD1 
  8430.  
  8431.  
  8432.  
  8433.  
  8434.  
  8435.  
  8436.  
  8437.  
  8438.  
  8439.  
  8440.  
  8441.  
  8442.  
  8443.  
  8444.  
  8445.  
  8446.                                        Commands
  8447.                                        Page 127
  8448.  
  8449.  
  8450.  
  8451.  
  8452.  
  8453.  
  8454.  
  8455.                                   Q - PRO 4 Commands
  8456.  
  8457.  
  8458.      ASEAR
  8459.      -----
  8460.      ASEAR searches a memory array by increasing element number (or optionally
  8461.      by decreasing element number) for the value of an element that satisfies an
  8462.      expression.  If an element is found that satisfies the expression, the
  8463.      element number will be returned.  If not, the error path will be taken. 
  8464.  
  8465.      Syntax 1: ASEAR <name> {DOWN} USING <result> AT <expression>:error
  8466.  
  8467.      name           The name of the array to be searched
  8468.  
  8469.      result         The location to place the array element number if a match is
  8470.                     found. 
  8471.  
  8472.      expression     The expression to evaluate the array element.  All logical
  8473.                     expressions are valid.
  8474.  
  8475.      REMARKS        The optional DOWN keyword causes the command to searches the
  8476.                     array by decreasing number.
  8477.  
  8478.      Example:
  8479.           ASEAR MONTHS USING #N1 AT "JAN" = MONTHS[#N1]
  8480.  
  8481.  
  8482.      Syntax 2: ASEAR <name> {DOWN} USING <index> <{STARTING expression2}>AT
  8483.      <expression1>{:error}
  8484.  
  8485.      array name     The array to be searched.
  8486.  
  8487.      {DOWN}         Optionally searches the array from highest order element
  8488.                     number to lowest element number.
  8489.  
  8490.      {index}        On a match of the expression, this numeric data item will
  8491.                     contain the element number with the match.
  8492.      expression1    The expression that the element must match to get a "hit".
  8493.      expression2    The expression that defines the starting place for the
  8494.                     search--optional.
  8495.      Remarks        The use of this syntax allows searching an array (up or
  8496.                     down), and continuing the search after a match by modifying
  8497.                     the variable(s) in expression2 after a match.
  8498.  
  8499.  
  8500.  
  8501.  
  8502.  
  8503.  
  8504.  
  8505.  
  8506.                                        Commands
  8507.                                        Page 128
  8508.  
  8509.  
  8510.  
  8511.  
  8512.  
  8513.  
  8514.  
  8515.                                   Q - PRO 4 Commands
  8516.  
  8517.  
  8518.      BACKSPACE
  8519.      ---------
  8520.      BACKSPACE positions a RANDOM or INDEXED file to the record previous to the
  8521.      current position.  
  8522.  
  8523.      Syntax:   BACKSPACE <file number> {:<B>error}
  8524.  
  8525.      file number    The file number as a literal, or numeric data item.
  8526.      Remarks        An end-of-file error is generated if the file is empty or
  8527.                     already positioned at the first record in the file. 
  8528.  
  8529.      Example:
  8530.  
  8531.           (scan file 1 in reverse order, assuming already at file end)
  8532.  
  8533.      1000 BACKSPACE 1 :1001
  8534.           READ 1 NOADV
  8535.           COPY * FROM 1
  8536.           GOTO 1000
  8537.      1001 ERROR "END OF FILE"
  8538.  
  8539.  
  8540.  
  8541.  
  8542.  
  8543.  
  8544.  
  8545.  
  8546.  
  8547.  
  8548.  
  8549.  
  8550.  
  8551.  
  8552.  
  8553.  
  8554.  
  8555.  
  8556.  
  8557.  
  8558.  
  8559.  
  8560.  
  8561.  
  8562.  
  8563.  
  8564.  
  8565.  
  8566.                                        Commands
  8567.                                        Page 129
  8568.  
  8569.  
  8570.  
  8571.  
  8572.  
  8573.  
  8574.  
  8575.                                   Q - PRO 4 Commands
  8576.  
  8577.  
  8578.      BEGIN
  8579.      -----
  8580.      BEGIN denotes the start of the structured construct.  (ENDBEGIN denotes the
  8581.      termination of the structured construct.)  BEGINs may be nested and may
  8582.      have any of the following modifiers.
  8583.  
  8584.      Syntax:   BEGIN {WHILE, UNTIL, IF}<logical condition>
  8585.  
  8586.      WHILE          Using this keyword, the statements within the BEGIN . . .
  8587.                     ENDBEGIN structure will be repetitively executed as long as
  8588.                     the logical condition is true.
  8589.      UNTIL          Using this keyword,  the statements within the BEGIN . . .
  8590.                     ENDBEGIN structure will be repetitively executed as long as
  8591.                     the logical condition is <BI>not  true.
  8592.      IF             When the IF keyword is used, the statements within the BEGIN
  8593.                     . . . ENDBEGIN structure will be executed once.
  8594.      logical 
  8595.        condition    A logically evaluatable expression.
  8596.  
  8597.      Remarks        BEGIN is allowed one modifier, either, IF, WHILE, or UNTIL.
  8598.  
  8599.  
  8600.      A BEGIN construct with no modifier (WHILE, UNTIL, IF) must be ended with an
  8601.      ENDBEGIN with a modifier of WHILE, UNTIL or IF.
  8602.  
  8603.  
  8604.      BEGIN WHILE logical condition>i is the start of a structured construct that
  8605.      will execute during the time that the conditional value is true.  If the
  8606.      condition remains true, the construct will execute forever.
  8607.  
  8608.  
  8609.      Examples:
  8610.  
  8611.      BEGIN WHILE A GT 0
  8612.           SUB &VALUE(100) FROM A
  8613.           READ 100
  8614.      ENDBEGIN
  8615.  
  8616.           This code will execute during the time that A is greater than 0.  If A
  8617.           is never greater than 0, the code will be ignored.
  8618.  
  8619.      BEGIN UNTIL A EQ 10
  8620.           ADD 1 TO A
  8621.      ENDBEGIN
  8622.  
  8623.           This code will continue executing as long as A is not equal to 10.
  8624.  
  8625.  
  8626.                                        Commands
  8627.                                        Page 130
  8628.  
  8629.  
  8630.  
  8631.  
  8632.  
  8633.  
  8634.  
  8635.                                   Q - PRO 4 Commands
  8636.  
  8637.  
  8638.  
  8639.      BEGIN IF A NEQ 0
  8640.           CALL ZERO_ROUT
  8641.      ENDBEGIN
  8642.  
  8643.           This code will execute only if A is not equal to 0.
  8644.  
  8645.      ELSE and ELSE IF
  8646.      ----------------
  8647.      ELSE and ELSE IF are used only with the BEGIN IF construct.  They provide
  8648.      excellent conditional controls.  The structure is:
  8649.  
  8650.      BEGIN IF<condition 1>
  8651.                statements  executed only if condition 1 is true
  8652.      ELSE IF<condition 2>
  8653.                statements  executed only if condition 2 is true
  8654.      ELSE
  8655.                statements  executed if neither condition 1 nor 
  8656.                    condition 2 is true.
  8657.      ENDBEGIN
  8658.  
  8659.      Examples:
  8660.  
  8661.      BEGIN IF #N1 = 1
  8662.                CALL SUB_ONE
  8663.                CALL SUB_ONE_A
  8664.                SET #B1
  8665.           ELSE IF #N1 = 2
  8666.                CALL SUB_TWO
  8667.                CALL SUB_TWO_A
  8668.                RESET #B1
  8669.           ELSE
  8670.                CALL MAIN_SUB
  8671.                CALL MAIN_SUB_A
  8672.      ENDBEGIN
  8673.  
  8674.           If #N1 equals 1, call subroutines SUB_ONE and SUB_ONE_A and SET #B1. 
  8675.           If #N1 equals 2, call subroutines SUB_TWO and SUB_TWO_A and RESET #B1. 
  8676.           If #N1 does not equal 1 or two, call subroutines MAIN_SUB and
  8677.           MAIN_SUB_A.
  8678.  
  8679.      A variation of the BEGIN/ENDBEGIN pairing is putting the condition after
  8680.      the ENDBEGIN.
  8681.  
  8682.      Examples:
  8683.  
  8684.  
  8685.  
  8686.                                        Commands
  8687.                                        Page 131
  8688.  
  8689.  
  8690.  
  8691.  
  8692.  
  8693.  
  8694.  
  8695.                                   Q - PRO 4 Commands
  8696.  
  8697.  
  8698.      BEGIN
  8699.           SUB 1 FROM A
  8700.      ENDBEGIN WHILE A LT 100
  8701.  
  8702.      BEGIN
  8703.           ADD 1 TO A
  8704.      ENDBEGIN UNTIL A GT #N1
  8705.  
  8706.  
  8707.  
  8708.  
  8709.  
  8710.  
  8711.  
  8712.  
  8713.  
  8714.  
  8715.  
  8716.  
  8717.  
  8718.  
  8719.  
  8720.  
  8721.  
  8722.  
  8723.  
  8724.  
  8725.  
  8726.  
  8727.  
  8728.  
  8729.  
  8730.  
  8731.  
  8732.  
  8733.  
  8734.  
  8735.  
  8736.  
  8737.  
  8738.  
  8739.  
  8740.  
  8741.  
  8742.  
  8743.  
  8744.  
  8745.  
  8746.                                        Commands
  8747.                                        Page 132
  8748.  
  8749.  
  8750.  
  8751.  
  8752.  
  8753.  
  8754.  
  8755.                                   Q - PRO 4 Commands
  8756.  
  8757.  
  8758.      BELL
  8759.      ----
  8760.      The BELL command causes the audible alarm to sound (if supported by the
  8761.      hardware).
  8762.  
  8763.      Syntax:   BELL
  8764.  
  8765.  
  8766.  
  8767.  
  8768.  
  8769.  
  8770.  
  8771.  
  8772.  
  8773.  
  8774.  
  8775.  
  8776.  
  8777.  
  8778.  
  8779.  
  8780.  
  8781.  
  8782.  
  8783.  
  8784.  
  8785.  
  8786.  
  8787.  
  8788.  
  8789.  
  8790.  
  8791.  
  8792.  
  8793.  
  8794.  
  8795.  
  8796.  
  8797.  
  8798.  
  8799.  
  8800.  
  8801.  
  8802.  
  8803.  
  8804.  
  8805.  
  8806.                                        Commands
  8807.                                        Page 133
  8808.  
  8809.  
  8810.  
  8811.  
  8812.  
  8813.  
  8814.  
  8815.                                   Q - PRO 4 Commands
  8816.  
  8817.  
  8818.      BUFFER
  8819.      ------
  8820.      The BUFFER command changes the size of the keyboard buffer (used to buffer
  8821.      up keystrokes while programming statements are being executed).  The
  8822.      default size of this buffer is 32 characters.  It may be set to any size
  8823.      between 0 and 255.
  8824.  
  8825.      Setting the buffer to zero (0) will speed processing of files and screens. 
  8826.      However, when set to 0, the BREAK procedure, if used, will be disabled. 
  8827.      Also, the machine keyboard buffer, if there is one, is flushed when a
  8828.      BUFFER statement is executed.
  8829.  
  8830.      Syntax:   BUFFER <numeric data item>
  8831.  
  8832.      numeric data item   A literal or other numeric data item.
  8833.  
  8834.      Examples:
  8835.  
  8836.           BUFFER 100
  8837.           BUFFER #N0
  8838.  
  8839.  
  8840.  
  8841.  
  8842.  
  8843.  
  8844.  
  8845.  
  8846.  
  8847.  
  8848.  
  8849.  
  8850.  
  8851.  
  8852.  
  8853.  
  8854.  
  8855.  
  8856.  
  8857.  
  8858.  
  8859.  
  8860.  
  8861.  
  8862.  
  8863.  
  8864.  
  8865.  
  8866.                                        Commands
  8867.                                        Page 134
  8868.  
  8869.  
  8870.  
  8871.  
  8872.  
  8873.  
  8874.  
  8875.                                   Q - PRO 4 Commands
  8876.  
  8877.  
  8878.      BROFF
  8879.      -----
  8880.      BROFF disables the current PROC BREAK (if any).
  8881.           
  8882.  
  8883.      Syntax:   BROFF
  8884.  
  8885.      Example:
  8886.           BROFF
  8887.  
  8888.  
  8889.  
  8890.      BRON
  8891.      ----
  8892.      BRON enables the current PROC BREAK (if any).
  8893.  
  8894.      Syntax:   BRON
  8895.  
  8896.      Example:  BRON
  8897.  
  8898.  
  8899.  
  8900.  
  8901.  
  8902.  
  8903.  
  8904.  
  8905.  
  8906.  
  8907.  
  8908.  
  8909.  
  8910.  
  8911.  
  8912.  
  8913.  
  8914.  
  8915.  
  8916.  
  8917.  
  8918.  
  8919.  
  8920.  
  8921.  
  8922.  
  8923.  
  8924.  
  8925.  
  8926.                                        Commands
  8927.                                        Page 135
  8928.  
  8929.  
  8930.  
  8931.  
  8932.  
  8933.  
  8934.  
  8935.                                   Q - PRO 4 Commands
  8936.  
  8937.  
  8938.      CALC
  8939.      ----
  8940.      CALC allows the computation of algebraic expressions in those circumstances
  8941.      where the use of the ADD, SUB, MUL, or DIV commands would be clumsy.
  8942.  
  8943.      Syntax:   CALC<data item> = <expression>
  8944.  
  8945.      data item      The data item may be any valid numeric data item.
  8946.      expression     The expression is an algebraic expression which may contain
  8947.                     nested parentheses and uses the following operators and
  8948.                     functions:
  8949.  
  8950.                + = addition             $LN       $OFFSET
  8951.                - = subtraction          $ETOX     $FIELD
  8952.                * = multiplication       $INT
  8953.                / = division
  8954.                ^ = exponentiation 
  8955.           
  8956.      Multiplication, division, and exponentiation have precedence over addition
  8957.      and subtraction, unless overridden with parentheses.   Exponentiation, $LN,
  8958.      $ETOX, and $INT require MATHLIB to be loaded on 8 bit systems.
  8959.  
  8960.      Examples:
  8961.  
  8962.           CALC TOTAL = FLD1 + FLD2 + #INT(&FLD[1])
  8963.           CALC $FIELD[#N0] = (ACCTBAL+5) } 3
  8964.           CALC AVERAGE = (SUM1+SUM2+SUM3+SUM4+SUM5)}5
  8965.           CALC SQUARE = NUM ^ 2
  8966.           CALC COMPLEX=(((FLD1+3)}(FLD2*7))-#N[CUSTTYPE])+ 11.5
  8967.  
  8968.  
  8969.  
  8970.  
  8971.  
  8972.  
  8973.  
  8974.  
  8975.  
  8976.  
  8977.  
  8978.  
  8979.  
  8980.  
  8981.  
  8982.  
  8983.  
  8984.  
  8985.  
  8986.                                        Commands
  8987.                                        Page 136
  8988.  
  8989.  
  8990.  
  8991.  
  8992.  
  8993.  
  8994.  
  8995.                                   Q - PRO 4 Commands
  8996.  
  8997.  
  8998.      CALL
  8999.      ----
  9000.      CALL invokes another procedure.  Control is returned to the statement
  9001.      following the CALL when the CALLed procedure executes a RETURN statement. 
  9002.      A maximum of 20 CALL and/or FOR statements may be nested.
  9003.  
  9004.      Syntax:   CALL <procedure>
  9005.  
  9006.      procedure      A procedure name.  Any procedure may be CALLed.  It is the
  9007.                     responsibility of the programmer to insure that the CALLed
  9008.                     procedure returns to the calling procedure.  On RETURN, the
  9009.                     next sequential statement will be executed    
  9010.  
  9011.  
  9012.      The procedure may be replaced by an indexed table name (i.e.,
  9013.      PROCTBL[#N3]).  This allows a computed call facility, affording great
  9014.      flexibility to the programmer.  The table so referenced must consist of a
  9015.      series of 1-item entries, each item being the name of a procedure.  Each
  9016.      item is referenced by its position in the table, starting with 0 as the
  9017.      index of the first position.
  9018.  
  9019.      Examples:
  9020.  
  9021.           CALL ALPHA1
  9022.           CALL PRCTABLE[#N1]
  9023.  
  9024.  
  9025.  
  9026.  
  9027.  
  9028.  
  9029.  
  9030.  
  9031.  
  9032.  
  9033.  
  9034.  
  9035.  
  9036.  
  9037.  
  9038.  
  9039.  
  9040.  
  9041.  
  9042.  
  9043.  
  9044.  
  9045.  
  9046.                                        Commands
  9047.                                        Page 137
  9048.  
  9049.  
  9050.  
  9051.  
  9052.  
  9053.  
  9054.  
  9055.                                   Q - PRO 4 Commands
  9056.  
  9057.  
  9058.      CENTER
  9059.      ------
  9060.      The CENTER command centers data in a string data item.  Centering will
  9061.      occur even in fields defined as right or left justified.
  9062.  
  9063.      Syntax:   CENTER <data item>
  9064.  
  9065.      Example:  CENTER BANNER
  9066.  
  9067.  
  9068.  
  9069.  
  9070.  
  9071.  
  9072.  
  9073.  
  9074.  
  9075.  
  9076.  
  9077.  
  9078.  
  9079.  
  9080.  
  9081.  
  9082.  
  9083.  
  9084.  
  9085.  
  9086.  
  9087.  
  9088.  
  9089.  
  9090.  
  9091.  
  9092.  
  9093.  
  9094.  
  9095.  
  9096.  
  9097.  
  9098.  
  9099.  
  9100.  
  9101.  
  9102.  
  9103.  
  9104.  
  9105.  
  9106.                                        Commands
  9107.                                        Page 138
  9108.  
  9109.  
  9110.  
  9111.  
  9112.  
  9113.  
  9114.  
  9115.                                   Q - PRO 4 Commands
  9116.  
  9117.  
  9118.      CHAIN
  9119.      -----
  9120.      The CHAIN command brings in another segment of the application.  It causes
  9121.      the named format file to be loaded from disk, its associated screen to be
  9122.      displayed, and processing to continue.  The file name may be any valid
  9123.      string data item.  All register settings, open files and file buffers are
  9124.      maintained across a chain statement, whereas variables are not.
  9125.  
  9126.      Syntax:   CHAIN <name> {:error} 
  9127.  
  9128.      filename       The actual filename in quotes or a valid filename in a
  9129.                     string data item.
  9130.      error          Label to jump to if there is an error.
  9131.      Remarks        If a string data item is to be used, it is highly
  9132.                     recommended that it be moved to a string register trimmed as
  9133.                     shown in the code below.  This will preclude trailing blanks
  9134.                     confusing the operating system.
  9135.  
  9136.                     MOVE VARIABLE TO #S0 TRIMMED
  9137.                     CHAIN #S0
  9138.  
  9139.      Examples:
  9140.           CHAIN "MENU2"
  9141.           CHAIN #S0 :100
  9142.  
  9143.  
  9144.  
  9145.  
  9146.  
  9147.  
  9148.  
  9149.  
  9150.  
  9151.  
  9152.  
  9153.  
  9154.  
  9155.  
  9156.  
  9157.  
  9158.  
  9159.  
  9160.  
  9161.  
  9162.  
  9163.  
  9164.  
  9165.  
  9166.                                        Commands
  9167.                                        Page 139
  9168.  
  9169.  
  9170.  
  9171.  
  9172.  
  9173.  
  9174.  
  9175.                                   Q - PRO 4 Commands
  9176.  
  9177.  
  9178.      CLEAR
  9179.      -----
  9180.      The CLEAR command causes the contents of a screen data field to be cleared
  9181.      to spaces.
  9182.  
  9183.      Syntax:   CLEAR <field or *>
  9184.  
  9185.      field          The literal name of the field or the result of a $FIELD
  9186.                     function.
  9187.      *              If the * option is used instead of a specific field name,
  9188.                     then all enterable, unlocked, and unduplicated fields on the
  9189.                     screen are cleared.
  9190.  
  9191.      Examples:
  9192.  
  9193.           CLEAR CUSTNO
  9194.           CLEAR $FIELD[#F]
  9195.           CLEAR *
  9196.  
  9197.  
  9198.  
  9199.  
  9200.  
  9201.  
  9202.  
  9203.  
  9204.  
  9205.  
  9206.  
  9207.  
  9208.  
  9209.  
  9210.  
  9211.  
  9212.  
  9213.  
  9214.  
  9215.  
  9216.  
  9217.  
  9218.  
  9219.  
  9220.  
  9221.  
  9222.  
  9223.  
  9224.  
  9225.  
  9226.                                        Commands
  9227.                                        Page 140
  9228.  
  9229.  
  9230.  
  9231.  
  9232.  
  9233.  
  9234.  
  9235.                                   Q - PRO 4 Commands
  9236.  
  9237.  
  9238.      CLOSE
  9239.      -----
  9240.      CLOSE causes a data file to be closed, and the directory for the disk on
  9241.      which it resides to be updated.  All files should be closed when no longer
  9242.      needed.  Q-PRO 4 will close any files left open before returning to the
  9243.      operating system.
  9244.  
  9245.      Syntax:   CLOSE <file number> {:error}
  9246.  
  9247.      file number         The file number as a literal or symbolic data item.
  9248.      error               The label to jump to if there is an error.
  9249.      Remarks             If no file number is given, then the system will close
  9250.                          all open files, and reset the file control system (the
  9251.                          currently logged drive is preserved).
  9252.  
  9253.      Examples:
  9254.           CLOSE 1
  9255.           CLOSE 99 :320
  9256.           CLOSE
  9257.  
  9258.  
  9259.  
  9260.  
  9261.  
  9262.  
  9263.  
  9264.  
  9265.  
  9266.  
  9267.  
  9268.  
  9269.  
  9270.  
  9271.  
  9272.  
  9273.  
  9274.  
  9275.  
  9276.  
  9277.  
  9278.  
  9279.  
  9280.  
  9281.  
  9282.  
  9283.  
  9284.  
  9285.  
  9286.                                        Commands
  9287.                                        Page 141
  9288.  
  9289.  
  9290.  
  9291.  
  9292.  
  9293.  
  9294.  
  9295.                                   Q - PRO 4 Commands
  9296.  
  9297.  
  9298.      COMMENT
  9299.      A COMMENT line is ignored by Q-PRO 4 and is intended to aid in the
  9300.      self-documentation of programs.  A comment line may be preceded by a line
  9301.      number or label.  Comments are not loaded at runtime.
  9302.  
  9303.      Example:
  9304.  
  9305.      * THIS IS A COMMENT
  9306.      102: * THIS IS A COMMENT WITH A LABEL
  9307.  
  9308.  
  9309.  
  9310.  
  9311.  
  9312.  
  9313.  
  9314.  
  9315.  
  9316.  
  9317.  
  9318.  
  9319.  
  9320.  
  9321.  
  9322.  
  9323.  
  9324.  
  9325.  
  9326.  
  9327.  
  9328.  
  9329.  
  9330.  
  9331.  
  9332.  
  9333.  
  9334.  
  9335.  
  9336.  
  9337.  
  9338.  
  9339.  
  9340.  
  9341.  
  9342.  
  9343.  
  9344.  
  9345.  
  9346.                                        Commands
  9347.                                        Page 142
  9348.  
  9349.  
  9350.  
  9351.  
  9352.  
  9353.  
  9354.  
  9355.                                   Q - PRO 4 Commands
  9356.  
  9357.  
  9358.      CONCAT
  9359.      ------
  9360.      CONCAT concatenates a set of string or numeric data items into one string
  9361.      data item.
  9362.  
  9363.      Syntax:   CONCAT <string> {TRIMMED} + <string>  {TRIMMED} INTO <string>
  9364.                {TRIMMED}
  9365.  
  9366.      string         A literal string or string data item.
  9367.      TRIMMED        This operator truncates trailing spaces of the string data
  9368.                     item preceding it.
  9369.      INTO           The INTO keyword points to the string data item where the
  9370.                     concatenated will be placed.  It may <BI>not be a literal,
  9371.                     however it may be one of the non-literal string data items
  9372.                     in the command.
  9373.  
  9374.      Examples:
  9375.       
  9376.           CONCAT #S1 TRIMMED + #S2 + #N3 INTO FIELD TRIMMED
  9377.           CONCAT #S1 + ". " + &FIR[1] TRIMMED + " " + &LAS INTO #S2
  9378.  
  9379.      Partial strings may be concatenated as shown below:
  9380.  
  9381.           CONCAT #S1(1,4) + #S2(2,5) INTO #S1
  9382.                This expression concatenates string register one from character
  9383.                position 1 for four characters with string register two from
  9384.                character position 2 for 5 characters into string register 1. 
  9385.                There must be data in the partial string concatenated.  
  9386.  
  9387.  
  9388.  
  9389.  
  9390.  
  9391.  
  9392.  
  9393.  
  9394.  
  9395.  
  9396.  
  9397.  
  9398.  
  9399.  
  9400.  
  9401.  
  9402.  
  9403.  
  9404.  
  9405.  
  9406.                                        Commands
  9407.                                        Page 143
  9408.  
  9409.  
  9410.  
  9411.  
  9412.  
  9413.  
  9414.  
  9415.                                   Q - PRO 4 Commands
  9416.  
  9417.  
  9418.      COPY
  9419.      ----
  9420.      COPY moves data from the screen to a indexed or random file, from the file
  9421.      to the screen, or from a file to another file.  There must be a FID file
  9422.      for any data file used.  COPY moves only fields with identical names in the
  9423.      direction given.
  9424.  
  9425.           Syntax:   COPY <file # or *> <TO <file # or *> {:error}
  9426.  
  9427.      file #         The specific file number to COPY from or to.
  9428.      *              An asterisk (*) always refers to the screen whereas a number
  9429.                     or numeric data item always refers to a file number.
  9430.      Remarks        The programmer may take advantage of this feature with
  9431.                     selective naming of the screen data fields and the file data
  9432.                     fields.
  9433.  
  9434.                     If there is data in the I/O file buffer for the target of
  9435.                     the move which does not have the same name as those in the
  9436.                     record being moved, the old data will remain.  Normally this
  9437.                     is not a problem.  If you want the output buffer to be
  9438.                     pristine, use RCLEAR before the copy.
  9439.  
  9440.      Examples:
  9441.  
  9442.           COPY 1 TO *
  9443.                Moves all file fields from the record for file # 1 to fields with
  9444.                the same name on the screen.
  9445.  
  9446.           COPY 1 TO 2
  9447.                Moves file data fields with the same name from file # 1 to file #
  9448.                2.
  9449.  
  9450.  
  9451.  
  9452.  
  9453.  
  9454.  
  9455.  
  9456.  
  9457.  
  9458.  
  9459.  
  9460.  
  9461.  
  9462.  
  9463.  
  9464.  
  9465.  
  9466.                                        Commands
  9467.                                        Page 144
  9468.  
  9469.  
  9470.  
  9471.  
  9472.  
  9473.  
  9474.  
  9475.                                   Q - PRO 4 Commands
  9476.  
  9477.  
  9478.      CURSOR
  9479.      ------
  9480.      The CURSOR command positions the cursor independently of the displayed form
  9481.      and its fields.
  9482.  
  9483.      Syntax:   CURSOR <row>,<column>
  9484.  
  9485.      row            A value or expression that evaluates from 0 to the number of
  9486.                     rows minus 1 (23 on most CRTs).
  9487.      column         The column is an expression that evaluates from 0 to the
  9488.                     number of columns minus 1 (79 on most CRTs).
  9489.      Remarks        The cursor position is maintained only until control is
  9490.                     returned to the operator.  Then the cursor will move to the
  9491.                     next enterable field.
  9492.  
  9493.      Example:
  9494.  
  9495.           CURSOR 22, #N0+5
  9496.  
  9497.  
  9498.  
  9499.  
  9500.  
  9501.  
  9502.  
  9503.  
  9504.  
  9505.  
  9506.  
  9507.  
  9508.  
  9509.  
  9510.  
  9511.  
  9512.  
  9513.  
  9514.  
  9515.  
  9516.  
  9517.  
  9518.  
  9519.  
  9520.  
  9521.  
  9522.  
  9523.  
  9524.  
  9525.  
  9526.                                        Commands
  9527.                                        Page 145
  9528.  
  9529.  
  9530.  
  9531.  
  9532.  
  9533.  
  9534.  
  9535.                                   Q - PRO 4 Commands
  9536.  
  9537.  
  9538.      CURRENCY
  9539.      --------
  9540.      The CURRENCY command allows the user to change the currency symbol used in
  9541.      the output of the EDIT statement (default is $). $ is still used as the
  9542.      character in the edit picture to denote the placement of the currency
  9543.      symbol.
  9544.  
  9545.      Syntax:   CURRENCY<symbol>
  9546.  
  9547.      symbol         may be any character string or string data item up to five
  9548.                     characters long.  If it is omitted, the system reverts to
  9549.                     using $ as the output currency symbol.
  9550.  
  9551.      Examples:
  9552.  
  9553.           CURRENCY "DM"
  9554.           CURRENCY
  9555.  
  9556.  
  9557.  
  9558.  
  9559.  
  9560.  
  9561.  
  9562.  
  9563.  
  9564.  
  9565.  
  9566.  
  9567.  
  9568.  
  9569.  
  9570.  
  9571.  
  9572.  
  9573.  
  9574.  
  9575.  
  9576.  
  9577.  
  9578.  
  9579.  
  9580.  
  9581.  
  9582.  
  9583.  
  9584.  
  9585.  
  9586.                                        Commands
  9587.                                        Page 146
  9588.  
  9589.  
  9590.  
  9591.  
  9592.  
  9593.  
  9594.  
  9595.                                   Q - PRO 4 Commands
  9596.  
  9597.  
  9598.      DEBUG
  9599.      -----
  9600.      The DEBUG command invokes the runtime debugger for program debugging.  It
  9601.      is usually invoked by a function key during program development.  When
  9602.      invoked, the following debug commands are available:
  9603.             
  9604.      ?    Displays a list of commands on the screen.
  9605.      DI   Allows the user to display a single data item. 
  9606.                For example: 
  9607.                DI #S1 - Displays the contents of string register 1.
  9608.                DI &FIELD[1]- Displays the contents of the file field 
  9609.                    FIELD from file one.
  9610.  
  9611.                (Any data item may be displayed.  Boolean (Bit) registers many
  9612.                not be displayed.)
  9613.      SI   Sets a new value for any data item.
  9614.                For example:
  9615.                SI #S0 = "ABC" - Places the string ABC in #S0.
  9616.                SI #&FIELD[1] = 100 - Moves 100 into the file field.
  9617.      DV   Displays a list of defined memory variables on the screen.
  9618.      DS   Displays a list of screen fields on the screen.
  9619.      DO   Displays a list of open files on the screen.
  9620.      DF   Displays a list of fields for a particular file number on the screen.
  9621.                For example:
  9622.                DF 1 - Displays the fields for file 1.
  9623.      DM   Displays half a screen of memory starting at the given address.
  9624.                For example:
  9625.                DM 39284 - displays memory from 39284 decimal
  9626.                DM H800  - displays memory from 800 hex
  9627.      SM   Sets memory to the value specified at the location specified.
  9628.                For example:
  9629.                SM 100=1,2,3 - Sets memory at decimal 100 to 1, 
  9630.                    at decimal 101 to 2, and at decimal 102 to 3.
  9631.                SM H100=H4F - Sets memory at Hex 100 to Hex 4F.
  9632.      DB   Display the settings of the Boolean (BIT) registers.
  9633.      SB   Set a Boolean register.
  9634.                For example:
  9635.                SB 1 - Sets register 1
  9636.  
  9637.      RB   Resets a Boolean register.
  9638.                For example:
  9639.                RB 1 - Resets register 1
  9640.      EP   Enables the printer.  Any data printed on the screen will be echoed to
  9641.           the printer.
  9642.      DP   Disables the printer.  Data printed to the screen will go to the
  9643.           screen only.
  9644.  
  9645.  
  9646.                                        Commands
  9647.                                        Page 147
  9648.  
  9649.  
  9650.  
  9651.  
  9652.  
  9653.  
  9654.  
  9655.                                   Q - PRO 4 Commands
  9656.  
  9657.  
  9658.      ET   Enables trace.  
  9659.      DT   Disables trace.
  9660.      MA   Display memory available for files and variables.
  9661.      EX   Exit Debug and return to the application program.
  9662.  
  9663.      Remark    On 16 bit systems, DM and SM are used in conjunction with the
  9664.                command DEFSEG. 
  9665.  
  9666.      Example:
  9667.  
  9668.      PROC KEY9
  9669.           DEBUG          
  9670.           END
  9671.  
  9672.  
  9673.  
  9674.  
  9675.  
  9676.  
  9677.  
  9678.  
  9679.  
  9680.  
  9681.  
  9682.  
  9683.  
  9684.  
  9685.  
  9686.  
  9687.  
  9688.  
  9689.  
  9690.  
  9691.  
  9692.  
  9693.  
  9694.  
  9695.  
  9696.  
  9697.  
  9698.  
  9699.  
  9700.  
  9701.  
  9702.  
  9703.  
  9704.  
  9705.  
  9706.                                        Commands
  9707.                                        Page 148
  9708.  
  9709.  
  9710.  
  9711.  
  9712.  
  9713.  
  9714.  
  9715.                                   Q - PRO 4 Commands
  9716.  
  9717.  
  9718.      DEFSEG
  9719.      DEFSEG is used on 16 bit versions in conjunction with PEEK's, POKE's and
  9720.      DEBUG.  Since the peek and poke commands only allow access to the 64K
  9721.      runtime data area, DEFSEG is needed to set a new data segment.
  9722.  
  9723.      Syntax:   DEFSEG <expression>
  9724.  
  9725.      expression          must evaluate to a valid integer segment
  9726.  
  9727.      Example:
  9728.           DEFSEG 80
  9729.           PEEK 1,1,prnscn_flg
  9730.  
  9731.                Looks at the 'print screen in progress' flag on an IBM PC.
  9732.  
  9733.  
  9734.  
  9735.  
  9736.  
  9737.  
  9738.  
  9739.  
  9740.  
  9741.  
  9742.  
  9743.  
  9744.  
  9745.  
  9746.  
  9747.  
  9748.  
  9749.  
  9750.  
  9751.  
  9752.  
  9753.  
  9754.  
  9755.  
  9756.  
  9757.  
  9758.  
  9759.  
  9760.  
  9761.  
  9762.  
  9763.  
  9764.  
  9765.  
  9766.                                        Commands
  9767.                                        Page 149
  9768.  
  9769.  
  9770.  
  9771.  
  9772.  
  9773.  
  9774.  
  9775.                                   Q - PRO 4 Commands
  9776.  
  9777.  
  9778.      DIV
  9779.      ---
  9780.      DIV divides one numeric data item by another and optionally places the
  9781.      result in a third.
  9782.  
  9783.      Syntax:   DIV <data item 1> INTO <data item 2> {GIVING <data item 3>}
  9784.  
  9785.      data item 1    A valid numeric data item which is the divisor.
  9786.      INTO           This verb points to the dividend.  It must be a valid
  9787.                     numeric data item.  If the answer or quotient is to be
  9788.                     stored here, it must <BI>not be a literal number.
  9789.      GIVING         Points the numeric data item where the result or quotient is
  9790.                     to be placed.
  9791.  
  9792.                     If the GIVING clause is not present, then the result is
  9793.                     stored in data item 2.
  9794.      Remarks        The keyword INTO may be replaced by a comma (,).
  9795.  
  9796.                     Refer to the Data Items section for legal types of data
  9797.                     items which may be used.
  9798.  
  9799.      Examples:
  9800.           DIV 2 INTO WHOLE GIVING HALF
  9801.           DIV #N0,#N3
  9802.           DIV COUNT,SUM GIVING AVG
  9803.  
  9804.  
  9805.  
  9806.  
  9807.  
  9808.  
  9809.  
  9810.  
  9811.  
  9812.  
  9813.  
  9814.  
  9815.  
  9816.  
  9817.  
  9818.  
  9819.  
  9820.  
  9821.  
  9822.  
  9823.  
  9824.  
  9825.  
  9826.                                        Commands
  9827.                                        Page 150
  9828.  
  9829.  
  9830.  
  9831.  
  9832.  
  9833.  
  9834.  
  9835.                                   Q - PRO 4 Commands
  9836.  
  9837.  
  9838.      EDIT
  9839.      ----
  9840.      EDIT gives the capability to format numeric data items according to a
  9841.      picture of the desired result.  This picture uses descriptor characters to
  9842.      control leading zeros, decimal point placement, etc.
  9843.  
  9844.      Syntax: EDIT <data1> USING <picture> INTO  <data2> {:<B>error}
  9845.  
  9846.      data1          Must be a numeric expression.
  9847.      picture        The format picture is a string consisting of a meaningful
  9848.                     combination of the following characters:
  9849.      "*"            Specifies that leading zero fill is to be replaced by
  9850.                     leading '*' characters instead.
  9851.  
  9852.      $              Specifies that the leftmost digit will be preceded by a
  9853.                     dollar sign.
  9854.  
  9855.      -              May be placed in leading or trailing position. Specifies
  9856.                     that if the number is negative, a sign will be inserted in
  9857.                     the designated position.
  9858.  
  9859.      +              May be placed in leading or trailing position. Specifies
  9860.                     that the appropriate sign (+ or -) will be inserted in the
  9861.                     designated position.
  9862.  
  9863.      Z              Specifies that a digit is to be placed in this position in
  9864.                     the formatted output.  Leading zeroes are suppressed.
  9865.  
  9866.      9              Specifies that a digit is to be placed in this position. 
  9867.                     Leading zeros are not suppressed.
  9868.  
  9869.      .              Specifies that a decimal point is to be placed in this
  9870.                     position.
  9871.  
  9872.      ,              Specifies that a comma will be inserted in the output area
  9873.                     if the first non-zero digit occurs to the right of the
  9874.                     comma.
  9875.       
  9876.      data2          Data item 2 may be a string field or register.  If no
  9877.                     numerically invalid characters have been introduced as a
  9878.                     result of the editing process, data item 2 may also be
  9879.                     numeric.  Refer to the UNEDIT command for removing
  9880.                     numerically invalid characters.
  9881.  
  9882.      Examples:
  9883.           EDIT 12.3 USING "9999.9" INTO #S0  =  0012.3
  9884.  
  9885.  
  9886.                                        Commands
  9887.                                        Page 151
  9888.  
  9889.  
  9890.  
  9891.  
  9892.  
  9893.  
  9894.  
  9895.                                   Q - PRO 4 Commands
  9896.  
  9897.  
  9898.           EDIT 234.98 USING "*$*ZZZ,*ZZZ.99" INTO #S1 = ***$234.98
  9899.           EDIT 1234.98 USING "*$*ZZZ,*ZZZ.99" INTO #S1 = *$1,234.98
  9900.           EDIT $FIELD[#N0] USING "999999.99" INTO $FIELD[#N0]
  9901.  
  9902.  
  9903.  
  9904.      ELSE - ELSE IF
  9905.      --------------
  9906.      An ELSE or ELSE IF is a part of the BEGIN construct and is always
  9907.      associated with a BEGIN IF.  A BEGIN may have any number of IF or ELSE IF
  9908.      statements associated with it.  See BEGIN.
  9909.  
  9910.      Examples:
  9911.      BEGIN IF #N1 GT 100
  9912.                SUB 1 FROM #N2   
  9913.           ELSE IF #N1 LT 100
  9914.                ADD 1 TO #N2
  9915.           ELSE
  9916.                MOVE 0 TO #N2
  9917.      ENDBEGIN
  9918.  
  9919.  
  9920.  
  9921.  
  9922.  
  9923.  
  9924.  
  9925.  
  9926.  
  9927.  
  9928.  
  9929.  
  9930.  
  9931.  
  9932.  
  9933.  
  9934.  
  9935.  
  9936.  
  9937.  
  9938.  
  9939.  
  9940.  
  9941.  
  9942.  
  9943.  
  9944.  
  9945.  
  9946.                                        Commands
  9947.                                        Page 152
  9948.  
  9949.  
  9950.  
  9951.  
  9952.  
  9953.  
  9954.  
  9955.                                   Q - PRO 4 Commands
  9956.  
  9957.  
  9958.      END
  9959.      ---
  9960.      END marks the end of a procedure or table.  It should be treated as any
  9961.      other executable statement, as the examples will show.  When the END
  9962.      statement in a procedure is encountered, control is turned over to the
  9963.      operator in the next enterable field for data entry.
  9964.  
  9965.      Syntax:        END
  9966.  
  9967.      Examples:
  9968.           PROC NOTHING
  9969.                END
  9970.  
  9971.           PROC VERIFY0
  9972.                IF FLD1 EQ 0 THEN END
  9973.                ERROR "SHOULD HAVE BEEN 0"
  9974.                END
  9975.  
  9976.           TABLE STATES
  9977.           "PA",     "Pennsylvania"
  9978.           "TX",     "Texas"
  9979.           "NJ",     "New Jersey"
  9980.           END
  9981.  
  9982.  
  9983.  
  9984.  
  9985.  
  9986.  
  9987.  
  9988.  
  9989.  
  9990.  
  9991.  
  9992.  
  9993.  
  9994.  
  9995.  
  9996.  
  9997.  
  9998.  
  9999.  
  10000.  
  10001.  
  10002.  
  10003.  
  10004.  
  10005.  
  10006.                                        Commands
  10007.                                        Page 153
  10008.  
  10009.  
  10010.  
  10011.  
  10012.  
  10013.  
  10014.  
  10015.                                   Q - PRO 4 Commands
  10016.  
  10017.  
  10018.      ENDBEGIN
  10019.      --------
  10020.      ENDBEGIN denotes the end of the structured construct.  It may have any of
  10021.      the following modifiers:
  10022.  
  10023.      Syntax:   ENDBEGIN
  10024.           ENDBEGIN WHILE
  10025.           ENDBEGIN UNTIL
  10026.  
  10027.  
  10028.  
  10029.  
  10030.  
  10031.  
  10032.  
  10033.  
  10034.  
  10035.  
  10036.  
  10037.  
  10038.  
  10039.  
  10040.  
  10041.  
  10042.  
  10043.  
  10044.  
  10045.  
  10046.  
  10047.  
  10048.  
  10049.  
  10050.  
  10051.  
  10052.  
  10053.  
  10054.  
  10055.  
  10056.  
  10057.  
  10058.  
  10059.  
  10060.  
  10061.  
  10062.  
  10063.  
  10064.  
  10065.  
  10066.                                        Commands
  10067.                                        Page 154
  10068.  
  10069.  
  10070.  
  10071.  
  10072.  
  10073.  
  10074.  
  10075.                                   Q - PRO 4 Commands
  10076.  
  10077.  
  10078.      ENDFOR
  10079.      ------
  10080.      ENDFOR terminates a FOR loop.  When the ENDFOR statement is executed, the
  10081.      loop variable is incremented (or decremented, if the loop increment is
  10082.      negative) and then tested for exceeding the ending value of the loop.
  10083.  
  10084.      Syntax:   ENDFOR <loop variable>
  10085.  
  10086.      loop variable       The same loop variable that began the FOR loop.
  10087.  
  10088.      Remarks             If the ending value is not exceeded, then control
  10089.                          transfers back to the start of the loop (the next
  10090.                          statement after the corresponding FOR statement).  Note
  10091.                          that the program may exit FOR-ENDFOR loops prematurely
  10092.                          via GOTO statements.  CALL-RETURN and FOR-ENDFOR
  10093.                          management takes care of any aborted loops.
  10094.  
  10095.      Examples:
  10096.      FOR #N0 = 1 TO 100
  10097.      ENDFOR #N0
  10098.  
  10099.      FOR COUNTER = 1 TO 100
  10100.      ENDFOR COUNTER
  10101.  
  10102.  
  10103.  
  10104.  
  10105.  
  10106.  
  10107.  
  10108.  
  10109.  
  10110.  
  10111.  
  10112.  
  10113.  
  10114.  
  10115.  
  10116.  
  10117.  
  10118.  
  10119.  
  10120.  
  10121.  
  10122.  
  10123.  
  10124.  
  10125.  
  10126.                                        Commands
  10127.                                        Page 155
  10128.  
  10129.  
  10130.  
  10131.  
  10132.  
  10133.  
  10134.  
  10135.                                   Q - PRO 4 Commands
  10136.  
  10137.  
  10138.      ERASE
  10139.      -----
  10140.      ERASE removes a file from a disk.
  10141.  
  10142.      Syntax:   ERASE <file name> {:<error}
  10143.  
  10144.      filename       The file name may be any string literal, field, or register.
  10145.  
  10146.      Examples:
  10147.           ERASE "TEMP.$$$" :10
  10148.           ERASE #S0
  10149.           ERASE "B:OLDFILE.DAT"
  10150.  
  10151.  
  10152.  
  10153.  
  10154.  
  10155.  
  10156.  
  10157.  
  10158.  
  10159.  
  10160.  
  10161.  
  10162.  
  10163.  
  10164.  
  10165.  
  10166.  
  10167.  
  10168.  
  10169.  
  10170.  
  10171.  
  10172.  
  10173.  
  10174.  
  10175.  
  10176.  
  10177.  
  10178.  
  10179.  
  10180.  
  10181.  
  10182.  
  10183.  
  10184.  
  10185.  
  10186.                                        Commands
  10187.                                        Page 156
  10188.  
  10189.  
  10190.  
  10191.  
  10192.  
  10193.  
  10194.  
  10195.                                   Q - PRO 4 Commands
  10196.  
  10197.  
  10198.      ERROR
  10199.      -----
  10200.      The ERROR command displays an error message on the last line of the screen
  10201.      in a format compatible with system-generated error messages (for invalid
  10202.      keystrokes, etc.).
  10203.  
  10204.      Syntax:   ERROR <message>
  10205.  
  10206.      message        The message may be any data item.
  10207.  
  10208.  
  10209.      Examples:
  10210.           ERROR "FILE NOT FOUND"
  10211.           ERROR #S1
  10212.           ERROR "UNAUTHORIZED USER"
  10213.  
  10214.  
  10215.  
  10216.  
  10217.  
  10218.  
  10219.  
  10220.  
  10221.  
  10222.  
  10223.  
  10224.  
  10225.  
  10226.  
  10227.  
  10228.  
  10229.  
  10230.  
  10231.  
  10232.  
  10233.  
  10234.  
  10235.  
  10236.  
  10237.  
  10238.  
  10239.  
  10240.  
  10241.  
  10242.  
  10243.  
  10244.  
  10245.  
  10246.                                        Commands
  10247.                                        Page 157
  10248.  
  10249.  
  10250.  
  10251.  
  10252.  
  10253.  
  10254.  
  10255.                                   Q - PRO 4 Commands
  10256.  
  10257.  
  10258.      ERRTRAP
  10259.      -------
  10260.      The ERRTRAP command sets a label as an error branch, or clears such a label
  10261.      if an error branch was previously set.  (Refer to Programmer's Reference
  10262.      Manual for sample coding and a complete discussion.)
  10263.  
  10264.      Syntax:   ERRTRAP <label>
  10265.  
  10266.      label          Any label, numeric or alphanumeric.
  10267.      Remarks        If the label is not given, then any previous ERRTRAP set is
  10268.                     cleared.
  10269.  
  10270.      Examples:
  10271.           ERRTRAP 100
  10272.           ERRTRAP
  10273.  
  10274.  
  10275.  
  10276.  
  10277.  
  10278.  
  10279.  
  10280.  
  10281.  
  10282.  
  10283.  
  10284.  
  10285.  
  10286.  
  10287.  
  10288.  
  10289.  
  10290.  
  10291.  
  10292.  
  10293.  
  10294.  
  10295.  
  10296.  
  10297.  
  10298.  
  10299.  
  10300.  
  10301.  
  10302.  
  10303.  
  10304.  
  10305.  
  10306.                                        Commands
  10307.                                        Page 158
  10308.  
  10309.  
  10310.  
  10311.  
  10312.  
  10313.  
  10314.  
  10315.                                   Q - PRO 4 Commands
  10316.  
  10317.  
  10318.      EXEC
  10319.      ----
  10320.      EXEC causes the execution of a machine code routine that has been loaded
  10321.      into memory.
  10322.  
  10323.      Syntax:   EXEC <address>, <input string> {<,output string>} {<:<BI>error}
  10324.  
  10325.      address        The memory address at which to begin execution
  10326.      input string   A required string of data to be passed to the assembly
  10327.                     language routine.
  10328.      output string  An optional string for or returned data
  10329.  
  10330.      Remarks        The use of this and other machine code interface commands
  10331.                     presupposes that the programmer knows what he/she/it is
  10332.                     doing, since a call to an invalid address can clearly blow
  10333.                     the system away.  
  10334.  
  10335.  
  10336.  
  10337.  
  10338.  
  10339.  
  10340.  
  10341.  
  10342.  
  10343.  
  10344.  
  10345.  
  10346.  
  10347.  
  10348.  
  10349.  
  10350.  
  10351.  
  10352.  
  10353.  
  10354.  
  10355.  
  10356.  
  10357.  
  10358.  
  10359.  
  10360.  
  10361.  
  10362.  
  10363.  
  10364.  
  10365.  
  10366.                                        Commands
  10367.                                        Page 159
  10368.  
  10369.  
  10370.  
  10371.  
  10372.  
  10373.  
  10374.  
  10375.                                   Q - PRO 4 Commands
  10376.  
  10377.  
  10378.      FCOPY
  10379.      ------
  10380.      FCOPY copies a file.  No wild cards are allowed.
  10381.  
  10382.      Syntax:   FCOPY <filename1> TO <filename2> {<:error}
  10383.  
  10384.      filename1      The name of the file to be copied expressed as a literal, or
  10385.                     string data item.
  10386.      TO             The pointer to the file to be copied to.  A comma may be
  10387.                     substituted for the TO. 
  10388.      filename2      The name of the file to be copied to expressed as a literal. 
  10389.  
  10390.      Remarks        No wild cards are allowed.  If the destination file exists,
  10391.                     it will be overwritten.  
  10392.        
  10393.  
  10394.  
  10395.  
  10396.  
  10397.  
  10398.  
  10399.  
  10400.  
  10401.  
  10402.  
  10403.  
  10404.  
  10405.  
  10406.  
  10407.  
  10408.  
  10409.  
  10410.  
  10411.  
  10412.  
  10413.  
  10414.  
  10415.  
  10416.  
  10417.  
  10418.  
  10419.  
  10420.  
  10421.  
  10422.  
  10423.  
  10424.  
  10425.  
  10426.                                        Commands
  10427.                                        Page 160
  10428.  
  10429.  
  10430.  
  10431.  
  10432.  
  10433.  
  10434.  
  10435.                                   Q - PRO 4 Commands
  10436.  
  10437.  
  10438.      FILETYPE
  10439.      --------
  10440.      FILETYPE returns information about open files.
  10441.  
  10442.      Syntax:   FILETYPE<fileno>
  10443.  
  10444.      fileno         The file number as expressed as a literal or numeric data
  10445.                     item.
  10446.      Remarks        FILETYPE returns the information as shown below:
  10447.  
  10448.                Indexed Files            Random Files
  10449.                #N0 - File type               File type
  10450.                #N1 - Number of keys          Record length
  10451.                #N2 - Current Key
  10452.                #N3 - Record length
  10453.  
  10454.  
  10455.      Another use of FILETYPE is to determine if a file is open or closed.  If
  10456.      the error path is taken, the file is not open.
  10457.  
  10458.      Examples:
  10459.  
  10460.           FILETYPE 1
  10461.           FILETYPE #N6 :100
  10462.  
  10463.           FILETYPE 1
  10464.           KEY 1 USING 2
  10465.           POSN 1 TO KEY RELATIVE
  10466.           READ 1
  10467.           COPY 1 TO *
  10468.           KEY 1 USING #N2
  10469.  
  10470.                This code fragment illustrates changing keys and reverting to the
  10471.                original key which will be in #N2.       
  10472.  
  10473.  
  10474.  
  10475.  
  10476.  
  10477.  
  10478.  
  10479.  
  10480.  
  10481.  
  10482.  
  10483.  
  10484.  
  10485.  
  10486.                                        Commands
  10487.                                        Page 161
  10488.  
  10489.  
  10490.  
  10491.  
  10492.  
  10493.  
  10494.  
  10495.                                   Q - PRO 4 Commands
  10496.  
  10497.  
  10498.      FILL
  10499.      ----
  10500.      The FILL command causes unentered field fill in unlocked fields to be
  10501.      changed from the default character (space) to any character desired.
  10502.  
  10503.      Syntax:   FILL <string data item>
  10504.  
  10505.      string data item    A literal or string data item.
  10506.  
  10507.      Remarks             The FILL command affects the screen display only.  The
  10508.                          data, as seen by the program, is unchanged.  The value
  10509.                          for FILL will remain in effect across chains.  Normally
  10510.                          this command is used in PROC LOAD.
  10511.  
  10512.      Examples:
  10513.           FILL "." 
  10514.           FILL #S8
  10515.  
  10516.  
  10517.  
  10518.  
  10519.  
  10520.  
  10521.  
  10522.  
  10523.  
  10524.  
  10525.  
  10526.  
  10527.  
  10528.  
  10529.  
  10530.  
  10531.  
  10532.  
  10533.  
  10534.  
  10535.  
  10536.  
  10537.  
  10538.  
  10539.  
  10540.  
  10541.  
  10542.  
  10543.  
  10544.  
  10545.  
  10546.                                        Commands
  10547.                                        Page 162
  10548.  
  10549.  
  10550.  
  10551.  
  10552.  
  10553.  
  10554.  
  10555.                                   Q - PRO 4 Commands
  10556.  
  10557.  
  10558.      FOR
  10559.      ---
  10560.      FOR is the beginning of a control loop which increments or decrements a
  10561.      field, numeric variable or numeric register from a given starting value to
  10562.      a given ending value, with any given increment.
  10563.  
  10564.      Syntax:   FOR <loop variable> = <start> TO <end> {BY <increment>}
  10565.  
  10566.      loop variable  Any numeric register, numeric variable, numeric screen data
  10567.                     field, or numeric file data field.
  10568.      start          Initial value of the loop variable.  It may be any valid
  10569.                     numeric data item.
  10570.      TO             Range pointer.
  10571.      end            The ending value of the loop variable.  It may be any valid
  10572.                     numeric data item.
  10573.      BY             Points to the increment.
  10574.      increment      Value to add to the initial value on each iteration of the
  10575.                     loop.  It must be a valid numeric data item and may be
  10576.                     negative.
  10577.      Remarks        If the BY phrase is not given, then 1 is the assumed
  10578.                     increment.  The increment may be positive (in which case the
  10579.                     loop variable increases in value from start to end), or
  10580.                     negative (in which case the loop variable decreases in value
  10581.                     from start to end). The loop variable must be a register or
  10582.                     field; the start, end, and increment values may be any valid
  10583.                     numeric expression.  FOR loops may be nested; however, the
  10584.                     total of nested CALLs and FORs may not exceed 20.
  10585.  
  10586.      FOR loops are terminated by an ENDFOR statement, which must contain the
  10587.      name of the FOR loop variable whose loop is being terminated.
  10588.  
  10589.      Examples:
  10590.      FOR #N0 = 1 TO 20 BY 5
  10591.           .
  10592.           .
  10593.      ENDFOR #N0
  10594.  
  10595.  
  10596.      FOR COUNT = (#N0+1)}5 TO -10 BY INCR*3
  10597.           .
  10598.           .
  10599.      ENDFOR COUNT
  10600.  
  10601.  
  10602.  
  10603.  
  10604.  
  10605.  
  10606.                                        Commands
  10607.                                        Page 163
  10608.  
  10609.  
  10610.  
  10611.  
  10612.  
  10613.  
  10614.  
  10615.                                   Q - PRO 4 Commands
  10616.  
  10617.  
  10618.      FORMLOAD
  10619.      --------
  10620.      FORMLOAD sets an internal flag, so that on a future exit to the operating
  10621.      system command level for any reason, the format builder program (FB) is
  10622.      executed and the current application program is loaded ready for editing. 
  10623.      This provides a convenient feature during debugging when transitions
  10624.      between the format builder module and the runtime module are frequent.  It
  10625.      is normally the first statement in PROC LOAD.
  10626.  
  10627.      Syntax:   FORMLOAD
  10628.  
  10629.      Remarks        This flag will stay on until reset by NOFORMLOAD, even
  10630.                     through CHAIN operations.
  10631.  
  10632.  
  10633.  
  10634.  
  10635.  
  10636.  
  10637.  
  10638.  
  10639.  
  10640.  
  10641.  
  10642.  
  10643.  
  10644.  
  10645.  
  10646.  
  10647.  
  10648.  
  10649.  
  10650.  
  10651.  
  10652.  
  10653.  
  10654.  
  10655.  
  10656.  
  10657.  
  10658.  
  10659.  
  10660.  
  10661.  
  10662.  
  10663.  
  10664.  
  10665.  
  10666.                                        Commands
  10667.                                        Page 164
  10668.  
  10669.  
  10670.  
  10671.  
  10672.  
  10673.  
  10674.  
  10675.                                   Q - PRO 4 Commands
  10676.  
  10677.  
  10678.      FREE
  10679.      ----
  10680.      FREE deletes a key from an indexed file and effectively deletes the record.
  10681.  
  10682.      Syntax:   FREE <file number> {:<error>}
  10683.  
  10684.      file number         The file number expressed as a valid numeric data item.
  10685.      error               Label to branch to if the FREE fails.
  10686.      Remarks             Deleted records will remain in the file with a deleted
  10687.                          record flag until a new record is added.
  10688.  
  10689.                          The key must have been previously accessed via POSN and
  10690.                          READ statements.
  10691.  
  10692.      Example:
  10693.           POSN 1 TO #S0
  10694.           READ 1
  10695.           FREE 1
  10696.  
  10697.  
  10698.  
  10699.  
  10700.  
  10701.  
  10702.  
  10703.  
  10704.  
  10705.  
  10706.  
  10707.  
  10708.  
  10709.  
  10710.  
  10711.  
  10712.  
  10713.  
  10714.  
  10715.  
  10716.  
  10717.  
  10718.  
  10719.  
  10720.  
  10721.  
  10722.  
  10723.  
  10724.  
  10725.  
  10726.                                        Commands
  10727.                                        Page 165
  10728.  
  10729.  
  10730.  
  10731.  
  10732.  
  10733.  
  10734.  
  10735.                                   Q - PRO 4 Commands
  10736.  
  10737.  
  10738.      FSEAR
  10739.      -----
  10740.      FSEAR is used to search a data file on a record-by-record basis for the
  10741.      satisfaction of any logical condition.
  10742.  
  10743.      Syntax 1: FSEAR <file #> {NOADV} AT <condition> {:error}
  10744.  
  10745.      file #         The file number of the file to be searched.
  10746.      NOADV          If NOADV , the file is left positioned at the record which
  10747.                     it was loaded.
  10748.      AT             Points to the search condition.
  10749.      Condition      Any condition which is valid in an IF statement is valid for
  10750.                     FSEAR.
  10751.      Remarks        The file is searched, starting at the current position in
  10752.                     the file.  Searching will stop when either the condition is
  10753.                     true, or end of file.  If the condition is found, the record
  10754.                     for which the condition was true will be loaded, and the
  10755.                     file left positioned at the next record in the file.
  10756.  
  10757.                     Searching begins at the current file position.  For indexed
  10758.                     files, the search sequence is the current file key. If no
  10759.                     match is found, then an end-of-file error is caused.
  10760.  
  10761.      Examples:
  10762.           FSEAR 1 NOADV AT &CUSTNO[1] > 100  :99
  10763.           FSEAR 3 AT &TYPE[3] = TYPE AND &INV[3] GEQ &INV[2] :100
  10764.  
  10765.  
  10766.      Syntax 2:      FSEAR <file #> {NOADV} USING <string data item>:error
  10767.  
  10768.      NOADV               Do not advance the file after a match.
  10769.      USING               The keyword to denote a dynamic search argument.
  10770.      string data item    A string register, string field, or string variable
  10771.                          that contains the search condition.
  10772.  
  10773.      Examples:
  10774.           A file is to be searched for a match on a last name input by a user
  10775.           from the screen.  The screen data field name is NAME and the file data
  10776.           field name is LAST.  The code looks like this:
  10777.  
  10778.           MOVE "NAME = &LAST[1]" TO #S0
  10779.           FSEAR 1 USING #S0:100
  10780.  
  10781.           The file is searched sequentially until the condition NAME = &LAST[1]
  10782.           is met.  Then the next sequential instruction will be executed.  On no
  10783.           match, the next record will be read and tested; if end of file then
  10784.  
  10785.  
  10786.                                        Commands
  10787.                                        Page 166
  10788.  
  10789.  
  10790.  
  10791.  
  10792.  
  10793.  
  10794.  
  10795.                                   Q - PRO 4 Commands
  10796.  
  10797.  
  10798.           control will pass to line number 100.  Remember, when using this
  10799.           command, strings must match exactly for a match and the FSEAR command
  10800.           will begin searching at the current file position. 
  10801.  
  10802.  
  10803.  
  10804.  
  10805.  
  10806.  
  10807.  
  10808.  
  10809.  
  10810.  
  10811.  
  10812.  
  10813.  
  10814.  
  10815.  
  10816.  
  10817.  
  10818.  
  10819.  
  10820.  
  10821.  
  10822.  
  10823.  
  10824.  
  10825.  
  10826.  
  10827.  
  10828.  
  10829.  
  10830.  
  10831.  
  10832.  
  10833.  
  10834.  
  10835.  
  10836.  
  10837.  
  10838.  
  10839.  
  10840.  
  10841.  
  10842.  
  10843.  
  10844.  
  10845.  
  10846.                                        Commands
  10847.                                        Page 167
  10848.  
  10849.  
  10850.  
  10851.  
  10852.  
  10853.  
  10854.  
  10855.                                   Q - PRO 4 Commands
  10856.  
  10857.  
  10858.      GET
  10859.      ---
  10860.      GET moves a data field from a file buffer to a register or screen field.
  10861.  
  10862.      Syntax:   GET <data name or *> FROM <file number> <B>FOR <length> {TRIMMED}
  10863.                {:error}
  10864.  
  10865.      data name or *      This may be a register or field.
  10866.  
  10867.                          If the data name is an asterisk (*), then all
  10868.                          enterable, unlocked fields on the screen are filled
  10869.                          from the current position in the file buffer, in the
  10870.                          order they appear on the screen, starting with the
  10871.                          first unprotected field on the screen.
  10872.      file number         The file number must represent an open file.
  10873.      TRIMMED             If the keyword TRIMMED is present, then trailing spaces
  10874.                          are removed from the data as it is transferred from the
  10875.                          file buffer to the data item.  This is invalid in the
  10876.                          GET * usage of the statement.
  10877.      Remarks             It is not used when the movement from file buffer is
  10878.                          done with FID names or the COPY command.  With FID
  10879.                          names use the MOVE command.
  10880.  
  10881.                          Note that for sequential files, the normal sequence of
  10882.                          statements is to issue GET's until the end of a record,
  10883.                          and then issue a READ to bypass the carriage
  10884.                          return/line feed sequence which marks the end of a
  10885.                          sequential record. For random and indexed files issue a
  10886.                          READ first, followed by GETs to extract the data from
  10887.                          the file buffer.  Each GET issued advances the file
  10888.                          buffer pointer by the length of the GET.
  10889.  
  10890.      Examples:
  10891.           GET #N0 FROM 1 FOR 5 :4444
  10892.           GET CUSTNAME FROM 12 FOR 60 TRIMMED
  10893.           GET * FROM 1
  10894.  
  10895.  
  10896.  
  10897.  
  10898.  
  10899.  
  10900.  
  10901.  
  10902.  
  10903.  
  10904.  
  10905.  
  10906.                                        Commands
  10907.                                        Page 168
  10908.  
  10909.  
  10910.  
  10911.  
  10912.  
  10913.  
  10914.  
  10915.                                   Q - PRO 4 Commands
  10916.  
  10917.  
  10918.      GETDATE
  10919.      -------
  10920.      GETDATE loads an alphanumeric data item with the current system date. 
  10921.      (Refer also to SETDATE.)
  10922.  
  10923.      Syntax:   GETDATE <string data item>
  10924.  
  10925.      string data item    Any valid string data item except a literal.
  10926.      Remarks             The format of the retrieved date is MM/DD/YYYY
  10927.                          hh:mm:ss, where:
  10928.                          MM = MONTH          hh = hours
  10929.                          DD = DAY            mm = minutes
  10930.                          YYYY = YEAR         ss = seconds
  10931.  
  10932.      Example:
  10933.           GETDATE #S0
  10934.  
  10935.  
  10936.  
  10937.  
  10938.  
  10939.  
  10940.  
  10941.  
  10942.  
  10943.  
  10944.  
  10945.  
  10946.  
  10947.  
  10948.  
  10949.  
  10950.  
  10951.  
  10952.  
  10953.  
  10954.  
  10955.  
  10956.  
  10957.  
  10958.  
  10959.  
  10960.  
  10961.  
  10962.  
  10963.  
  10964.  
  10965.  
  10966.                                        Commands
  10967.                                        Page 169
  10968.  
  10969.  
  10970.  
  10971.  
  10972.  
  10973.  
  10974.  
  10975.                                   Q - PRO 4 Commands
  10976.  
  10977.  
  10978.      GOTO
  10979.      ----
  10980.      GOTO alters the sequential flow of command execution by forcing an
  10981.      immediate jump to the program location marked by a numeric or alphanumeric
  10982.      label.
  10983.  
  10984.      Syntax:   GOTO <label or line number>
  10985.  
  10986.      label or line number     A valid label or line number.
  10987.      Remarks                  Instead of an actual label being given, the
  10988.                               program may instead give a table name and index. 
  10989.                               Here, the destination of the GOTO is chosen as the
  10990.                               corresponding element of the table.  The table
  10991.                               used must consist of a series of 1-item lines,
  10992.                               each item being a label.  The first item in the
  10993.                               table is zero (0).  See also discussion in
  10994.                               Programmer's Reference Manual.
  10995.  
  10996.      Examples:
  10997.           GOTO 100
  10998.           GOTO DEM_LABEL
  10999.           GOTO LABTBL[#N0]
  11000.  
  11001.  
  11002.  
  11003.  
  11004.  
  11005.  
  11006.  
  11007.  
  11008.  
  11009.  
  11010.  
  11011.  
  11012.  
  11013.  
  11014.  
  11015.  
  11016.  
  11017.  
  11018.  
  11019.  
  11020.  
  11021.  
  11022.  
  11023.  
  11024.  
  11025.  
  11026.                                        Commands
  11027.                                        Page 170
  11028.  
  11029.  
  11030.  
  11031.  
  11032.  
  11033.  
  11034.  
  11035.                                   Q - PRO 4 Commands
  11036.  
  11037.  
  11038.      HELP
  11039.      ----
  11040.      The HELP command allows an unlimited number of help screens to be displayed
  11041.      by an application.
  11042.  
  11043.      Help screens are normal QNE format files built by FB, without enterable
  11044.      fields or PROCs (fields and PROCs will be ignored in help screens in any
  11045.      case).
  11046.       
  11047.      Syntax:   HELP <screen> {,<screen>,<screen>. . .}{:error}
  11048.  
  11049.      screen         The name of the help screen may be a literal in quotes, or a
  11050.                     valid string data item.
  11051.      Remarks        When the first help screen is displayed, the operator may
  11052.                     either press ESCAPE (in which case no more screens are
  11053.                     displayed), or any other key (in which case the next screen
  11054.                     is displayed).  After the last screen, any key will restore
  11055.                     the data entry screen in its original form.  The error
  11056.                     branch will be taken if a help screen cannot be found.
  11057.  
  11058.      Examples:
  11059.           HELP "B:HELP1","B:HELP2",#S1:123
  11060.           IF #F EQ 10 HELP "B:FID.HLP"
  11061.  
  11062.  
  11063.  
  11064.  
  11065.  
  11066.  
  11067.  
  11068.  
  11069.  
  11070.  
  11071.  
  11072.  
  11073.  
  11074.  
  11075.  
  11076.  
  11077.  
  11078.  
  11079.  
  11080.  
  11081.  
  11082.  
  11083.  
  11084.  
  11085.  
  11086.                                        Commands
  11087.                                        Page 171
  11088.  
  11089.  
  11090.  
  11091.  
  11092.  
  11093.  
  11094.  
  11095.                                   Q - PRO 4 Commands
  11096.  
  11097.  
  11098.      HOFF
  11099.      ----
  11100.  
  11101.      Syntax:   HOFF
  11102.  
  11103.      For the use of HOFF, see HON below.
  11104.  
  11105.  
  11106.  
  11107.  
  11108.  
  11109.  
  11110.  
  11111.  
  11112.  
  11113.  
  11114.  
  11115.  
  11116.  
  11117.  
  11118.  
  11119.  
  11120.  
  11121.  
  11122.  
  11123.  
  11124.  
  11125.  
  11126.  
  11127.  
  11128.  
  11129.  
  11130.  
  11131.  
  11132.  
  11133.  
  11134.  
  11135.  
  11136.  
  11137.  
  11138.  
  11139.  
  11140.  
  11141.  
  11142.  
  11143.  
  11144.  
  11145.  
  11146.                                        Commands
  11147.                                        Page 172
  11148.  
  11149.  
  11150.  
  11151.  
  11152.  
  11153.  
  11154.  
  11155.                                   Q - PRO 4 Commands
  11156.  
  11157.  
  11158.      HON
  11159.      ---
  11160.      HON turns the screen highlight on at the current cursor position.  
  11161.  
  11162.      Syntax:   HON
  11163.  
  11164.      Remarks        If highlights are not defined for this hardware, a blank
  11165.                     will be printed.  (This is the same as having a highlight
  11166.                     character placed on the screen in the background.)  HOFF
  11167.                     will turn the highlight off.  Note that different screens
  11168.                     will react differently depending on how the highlights are
  11169.                     implemented in hardware.
  11170.  
  11171.      Examples:
  11172.           For example, suppose that you want to highlight a message on the
  11173.           screen which will read "YOU FOOL" at screen position row 2, line 10. 
  11174.           The following will always highlight it:
  11175.  
  11176.           CURSOR 2,9
  11177.           HON
  11178.           PRINT "YOU FOOL"
  11179.           CURSOR 2, 19
  11180.           HOFF
  11181.  
  11182.           Be careful with this instruction if you use a variety of hardware. 
  11183.           Note that the highlight character requires a screen position.  Data
  11184.           previously printed in this location will not be restored.  
  11185.  
  11186.  
  11187.  
  11188.  
  11189.  
  11190.  
  11191.  
  11192.  
  11193.  
  11194.  
  11195.  
  11196.  
  11197.  
  11198.  
  11199.  
  11200.  
  11201.  
  11202.  
  11203.  
  11204.  
  11205.  
  11206.                                        Commands
  11207.                                        Page 173
  11208.  
  11209.  
  11210.  
  11211.  
  11212.  
  11213.  
  11214.  
  11215.                                   Q - PRO 4 Commands
  11216.  
  11217.  
  11218.      HOME
  11219.      ----
  11220.      HOME moves the cursor to the first enterable field on the screen and
  11221.      returns control to the operator for data entry.
  11222.  
  11223.      Syntax:   HOME
  11224.  
  11225.      Remarks        No more statements in the current procedure will be
  11226.                     executed.  If HOME is executed in PROC ENTER, the fields
  11227.                     will not be cleared.
  11228.  
  11229.  
  11230.  
  11231.  
  11232.  
  11233.  
  11234.  
  11235.  
  11236.  
  11237.  
  11238.  
  11239.  
  11240.  
  11241.  
  11242.  
  11243.  
  11244.  
  11245.  
  11246.  
  11247.  
  11248.  
  11249.  
  11250.  
  11251.  
  11252.  
  11253.  
  11254.  
  11255.  
  11256.  
  11257.  
  11258.  
  11259.  
  11260.  
  11261.  
  11262.  
  11263.  
  11264.  
  11265.  
  11266.                                        Commands
  11267.                                        Page 174
  11268.  
  11269.  
  11270.  
  11271.  
  11272.  
  11273.  
  11274.  
  11275.                                   Q - PRO 4 Commands
  11276.  
  11277.  
  11278.      HOMECLEAR
  11279.      ---------
  11280.      HOMECLEAR moves the cursor to the first enterable field on the screen and
  11281.      clears all enterable fields.  As in the HOME command, control is then
  11282.      returned to the operator for data entry.
  11283.  
  11284.      Syntax:   HOMECLEAR
  11285.  
  11286.  
  11287.  
  11288.  
  11289.  
  11290.  
  11291.  
  11292.  
  11293.  
  11294.  
  11295.  
  11296.  
  11297.  
  11298.  
  11299.  
  11300.  
  11301.  
  11302.  
  11303.  
  11304.  
  11305.  
  11306.  
  11307.  
  11308.  
  11309.  
  11310.  
  11311.  
  11312.  
  11313.  
  11314.  
  11315.  
  11316.  
  11317.  
  11318.  
  11319.  
  11320.  
  11321.  
  11322.  
  11323.  
  11324.  
  11325.  
  11326.                                        Commands
  11327.                                        Page 175
  11328.  
  11329.  
  11330.  
  11331.  
  11332.  
  11333.  
  11334.  
  11335.                                   Q - PRO 4 Commands
  11336.  
  11337.  
  11338.      HOST
  11339.      ----
  11340.      The HOST command establishes the host operating system.  No files may be
  11341.      open when this command is given.  A HOST statement takes precedence over
  11342.      the setting of the host bit in SETUP.  Refer to the Programmer's Reference
  11343.      Manual for hosts supported.
  11344.  
  11345.      Syntax:   HOST <string data item>
  11346.  
  11347.      Examples:
  11348.           HOST "NETWARE"
  11349.           HOST #S1
  11350.  
  11351.      HOSTS available.  (See READ.ME for changes.)
  11352.  
  11353.                OS or LAN                     HOST
  11354.                ---------                     ----
  11355.           IBM Network or PC-MOS         IBMNET or MSNET
  11356.           PC or MS-DOS                  PC-DOS or SINGLE
  11357.           NetWare (Novell)              NETWARE
  11358.  
  11359.  
  11360.  
  11361.  
  11362.  
  11363.  
  11364.  
  11365.  
  11366.  
  11367.  
  11368.  
  11369.  
  11370.  
  11371.  
  11372.  
  11373.  
  11374.  
  11375.  
  11376.  
  11377.  
  11378.  
  11379.  
  11380.  
  11381.  
  11382.  
  11383.  
  11384.  
  11385.  
  11386.                                        Commands
  11387.                                        Page 176
  11388.  
  11389.  
  11390.  
  11391.  
  11392.  
  11393.  
  11394.  
  11395.                                   Q - PRO 4 Commands
  11396.  
  11397.  
  11398.      IF
  11399.      --
  11400.      IF allows the conditional execution of program statements.
  11401.  
  11402.      Syntax:  IF <condition> {AND/OR <condition>} {THEN} <statement>
  11403.  
  11404.      condition      A condition is the comparison of two data items of like type
  11405.                     (i.e., either both are numeric or both are string) in the
  11406.                     format <data item 1> <operation> <data item 2> using the
  11407.                     following conditional operators:
  11408.  
  11409.      EQ or =        test for item 1 equal to item 2
  11410.      NEQ or <>      test for item 1 not equal to item 2
  11411.      LT or  <       test for item 1 less than item 2
  11412.      LE or <=       test for item 1 less than or equal to item 2
  11413.      GT or >        test for item 1 greater than item 2
  11414.      GE or >=       test for item 1 greater than or equal to item 2
  11415.      NLT            test for item 1 not less than item 2
  11416.      NLE            test for item 1 not less than or equal to item2
  11417.      NGT            test for item 1 not greater than item 2
  11418.      NGE            test for item 1 not greater than or equal to item 2
  11419.      ~              condition negation operator 
  11420.  
  11421.           AND/OR
  11422.           ------
  11423.           Multiple conditions may be joined by AND and OR operators, although
  11424.           these are evaluated from left to right without relative precedence. 
  11425.           Conditions may be nested with parentheses for complex logical
  11426.           evaluations.
  11427.  
  11428.           THEN
  11429.           ----
  11430.           The keyword THEN, used for readability, is optional.
  11431.  
  11432.      Remarks        Any executable statement may be performed as a result of an
  11433.                     IF statement, including (for example) an END or another IF
  11434.                     statement.
  11435.  
  11436.      Examples:
  11437.           IF CUSTNO EQ 0 THEN ERROR "INVALID NUMBER"
  11438.           IF #B0 SET THEN CALL SUB_ROUT1
  11439.           IF TYPE EQ "A" OR TYPE EQ "F" THEN MOVE 0 TO #N0
  11440.           IF #N0 > #N1 THEN MOVE "OVERFLOW" TO STATUS
  11441.           IF JOBNAME = "ZZZZZZ" GOTO 100
  11442.           IF TYPE EQ "A" OR TYPE EQ "B" OR TYPE EQ "C" CLEAR STAT
  11443.           IF KEY EQ 0 AND NAME EQ "" OR CUSTNO NLT 1000 GOTO 2090
  11444.  
  11445.  
  11446.                                        Commands
  11447.                                        Page 177
  11448.  
  11449.  
  11450.  
  11451.  
  11452.  
  11453.  
  11454.  
  11455.                                   Q - PRO 4 Commands
  11456.  
  11457.  
  11458.           IF MONTH <= 12 AND MONTH >= 1 THEN END
  11459.           IF (MON GT 5 AND DAY LT 1) AND MOON EQ "BLUE" THEN END
  11460.           IF ~A=B THEN GOTO NOT_EQUAL
  11461.           IF #B0 SET GOTO 100
  11462.           IF #B9 RESET IF STATUS NEQ "OPEN" MOVE "CLOSED" TO MSG
  11463.           IF #B2 SET ON #B3 SET ON #B4 RESET HOMECLEAR
  11464.           IF #B[#N4] RESET CALL READREC
  11465.  
  11466.  
  11467.  
  11468.  
  11469.  
  11470.  
  11471.  
  11472.  
  11473.  
  11474.  
  11475.  
  11476.  
  11477.  
  11478.  
  11479.  
  11480.  
  11481.  
  11482.  
  11483.  
  11484.  
  11485.  
  11486.  
  11487.  
  11488.  
  11489.  
  11490.  
  11491.  
  11492.  
  11493.  
  11494.  
  11495.  
  11496.  
  11497.  
  11498.  
  11499.  
  11500.  
  11501.  
  11502.  
  11503.  
  11504.  
  11505.  
  11506.                                        Commands
  11507.                                        Page 178
  11508.  
  11509.  
  11510.  
  11511.  
  11512.  
  11513.  
  11514.  
  11515.                                   Q - PRO 4 Commands
  11516.  
  11517.  
  11518.      INSTR
  11519.      -----
  11520.      INSTR searches a string for a substring match.
  11521.  
  11522.      Syntax:   INSTR <substring> {TRIMMED}, <string> {TRIMMED}, <result>
  11523.  
  11524.      substring      Substring to be searched for in the string.
  11525.      TRIMMED        Do not use trailing blanks in the substring for the match.
  11526.      string         String to be searched.
  11527.      TRIMMED        Do not use trailing blanks in the string to be searched for
  11528.                     the match.
  11529.      result         A numeric data item to place the result of the search.  If
  11530.                     there is a match, <result> will contain the first position
  11531.                     of the match in the searched string.  If no match, its value
  11532.                     will be 0.
  11533.  
  11534.      Example:
  11535.           INSTR "ABC", &FIELD[1] TRIMMED, #N0
  11536.                Looks for the string "ABC" in the file field FIELD, TRIMMED.  If
  11537.                found, place the location of the string in #N0.  If not found
  11538.                place a 0 in #N0.
  11539.  
  11540.  
  11541.  
  11542.  
  11543.  
  11544.  
  11545.  
  11546.  
  11547.  
  11548.  
  11549.  
  11550.  
  11551.  
  11552.  
  11553.  
  11554.  
  11555.  
  11556.  
  11557.  
  11558.  
  11559.  
  11560.  
  11561.  
  11562.  
  11563.  
  11564.  
  11565.  
  11566.                                        Commands
  11567.                                        Page 179
  11568.  
  11569.  
  11570.  
  11571.  
  11572.  
  11573.  
  11574.  
  11575.                                   Q - PRO 4 Commands
  11576.  
  11577.  
  11578.      JDPACK
  11579.      ------
  11580.      JDPACK calculates a Julian date and moves it into a data item.  
  11581.  
  11582.  
  11583.      Syntax:   JDPACK <date string> INTO <data item>
  11584.  
  11585.      date string         The date string must be of the form MM/DD/YYYY.
  11586.      data item           Any numeric data item except a literal.
  11587.      Remarks             The base date is December 31, 1977.  Therefore January
  11588.                          1, 1978 will JDPACK to 1 and December 30, 1977 will
  11589.                          JDPACK to -1.  Refer to JDUNPACK for converting Julian
  11590.                          dates to calendar dates. 
  11591.  
  11592.      Example
  11593.           JDPACK "04/25/1984" INTO #N1
  11594.  
  11595.  
  11596.  
  11597.  
  11598.  
  11599.  
  11600.  
  11601.  
  11602.  
  11603.  
  11604.  
  11605.  
  11606.  
  11607.  
  11608.  
  11609.  
  11610.  
  11611.  
  11612.  
  11613.  
  11614.  
  11615.  
  11616.  
  11617.  
  11618.  
  11619.  
  11620.  
  11621.  
  11622.  
  11623.  
  11624.  
  11625.  
  11626.                                        Commands
  11627.                                        Page 180
  11628.  
  11629.  
  11630.  
  11631.  
  11632.  
  11633.  
  11634.  
  11635.                                   Q - PRO 4 Commands
  11636.  
  11637.  
  11638.      JDUNPACK
  11639.      --------
  11640.      JDUNPACK converts the previously created Julian date in a data item to a
  11641.      calendar date.
  11642.  
  11643.      Syntax:   JDUNPACK <data item1> INTO <data item2>
  11644.  
  11645.      data item1          A previously packed Julian date.
  11646.      data item2          The destination data item must be a string.
  11647.      Remarks             Refer to JDPACK for generating the Julian date in a
  11648.                          data item.
  11649.  
  11650.      Example:
  11651.           JDUNPACK  #N1 INTO #S0
  11652.  
  11653.  
  11654.  
  11655.  
  11656.  
  11657.  
  11658.  
  11659.  
  11660.  
  11661.  
  11662.  
  11663.  
  11664.  
  11665.  
  11666.  
  11667.  
  11668.  
  11669.  
  11670.  
  11671.  
  11672.  
  11673.  
  11674.  
  11675.  
  11676.  
  11677.  
  11678.  
  11679.  
  11680.  
  11681.  
  11682.  
  11683.  
  11684.  
  11685.  
  11686.                                        Commands
  11687.                                        Page 181
  11688.  
  11689.  
  11690.  
  11691.  
  11692.  
  11693.  
  11694.  
  11695.                                   Q - PRO 4 Commands
  11696.  
  11697.  
  11698.      KEY
  11699.      ---
  11700.      KEY changes the current ISAM file KEY.
  11701.           
  11702.      Syntax:        KEY <file #> <B>USING <key #> 
  11703.  
  11704.      file #         The file number expressed as a literal or numeric data item.
  11705.      key #          The key number from 0 to 9, expressed as a literal or
  11706.                     numeric data item. 
  11707.      Remarks        Key 1 is the primary key and must be unique, but the
  11708.                     alternates (2-9) may be duplicates.  Duplicates will be in
  11709.                     primary key order.  For example, a record has two keys, NAME
  11710.                     and ZIP_CODE, and there are 3 records, MIKE 19438, JOHN
  11711.                     19438, and LARRY 19454.  Reading the file in primary key
  11712.                     order the records will be in the sequence:  JOHN 19438,
  11713.                     LARRY 19454 and MIKE 19438.  Reading in the second key order
  11714.                     the record will be in the sequence:  JOHN 19438, MIKE 19438,
  11715.                     and LARRY 19454.  Refer to POSN for the method of changing
  11716.                     the key using POSN.
  11717.  
  11718.                     Key 0 puts the file in physical order.
  11719.  
  11720.      Example:
  11721.           KEY 1 USING 3
  11722.           KEY #N1 USING #N3
  11723.  
  11724.  
  11725.  
  11726.  
  11727.  
  11728.  
  11729.  
  11730.  
  11731.  
  11732.  
  11733.  
  11734.  
  11735.  
  11736.  
  11737.  
  11738.  
  11739.  
  11740.  
  11741.  
  11742.  
  11743.  
  11744.  
  11745.  
  11746.                                        Commands
  11747.                                        Page 182
  11748.  
  11749.  
  11750.  
  11751.  
  11752.  
  11753.  
  11754.  
  11755.                                   Q - PRO 4 Commands
  11756.  
  11757.  
  11758.      LJUST
  11759.      -----
  11760.      LJUST left justifies data in a data item.
  11761.  
  11762.      Syntax:        LJUST <data item>
  11763.  
  11764.      data item      Any data item.
  11765.      Remarks        Left justification will occur even in fields defined as
  11766.                     right justified.
  11767.  
  11768.      Example:
  11769.           LJUST AMOUNT
  11770.           LJUST #S3
  11771.  
  11772.  
  11773.  
  11774.  
  11775.  
  11776.  
  11777.  
  11778.  
  11779.  
  11780.  
  11781.  
  11782.  
  11783.  
  11784.  
  11785.  
  11786.  
  11787.  
  11788.  
  11789.  
  11790.  
  11791.  
  11792.  
  11793.  
  11794.  
  11795.  
  11796.  
  11797.  
  11798.  
  11799.  
  11800.  
  11801.  
  11802.  
  11803.  
  11804.  
  11805.  
  11806.                                        Commands
  11807.                                        Page 183
  11808.  
  11809.  
  11810.  
  11811.  
  11812.  
  11813.  
  11814.  
  11815.                                   Q - PRO 4 Commands
  11816.  
  11817.  
  11818.      LOAD
  11819.      ----
  11820.      The LOAD command loads a machine code file into memory at the indicated
  11821.      address.  
  11822.  
  11823.      Syntax:   LOAD <file name>, <address> {:error}
  11824.  
  11825.      file name      The name of the file to be loaded as a literal in quotes or
  11826.                     as a string data item.
  11827.      address        The address at which to load the machine language program.
  11828.      Remarks        The error branch is taken if the file cannot be opened. 
  11829.                     Otherwise, the file is loaded into memory.  The responsi-
  11830.                     bility of making sure the file fits in memory is the
  11831.                     programmer's.  Refer to the Techniques Chapter for more
  11832.                     details.
  11833.  
  11834.      Example:
  11835.           LOAD "ROUTINES.COM", 48532  :897
  11836.  
  11837.  
  11838.  
  11839.  
  11840.  
  11841.  
  11842.  
  11843.  
  11844.  
  11845.  
  11846.  
  11847.  
  11848.  
  11849.  
  11850.  
  11851.  
  11852.  
  11853.  
  11854.  
  11855.  
  11856.  
  11857.  
  11858.  
  11859.  
  11860.  
  11861.  
  11862.  
  11863.  
  11864.  
  11865.  
  11866.                                        Commands
  11867.                                        Page 184
  11868.  
  11869.  
  11870.  
  11871.  
  11872.  
  11873.  
  11874.  
  11875.                                   Q - PRO 4 Commands
  11876.  
  11877.  
  11878.      LOCK
  11879.      ----
  11880.      LOCK makes a normally enterable screen data field unavailable to the
  11881.      operator.  The operator may not enter the field until a corresponding
  11882.      UNLOCK statement is executed.
  11883.  
  11884.      Syntax:   LOCK<screen data field name>
  11885.  
  11886.      screen data field name   A valid screen data field name.
  11887.      Remarks                  Locked fields will not be accessed in GET * or PUT
  11888.                               * statements.
  11889.  
  11890.      Example:
  11891.           LOCK CUSTNO
  11892.           LOCK $FIELD[#N8]
  11893.  
  11894.  
  11895.  
  11896.  
  11897.  
  11898.  
  11899.  
  11900.  
  11901.  
  11902.  
  11903.  
  11904.  
  11905.  
  11906.  
  11907.  
  11908.  
  11909.  
  11910.  
  11911.  
  11912.  
  11913.  
  11914.  
  11915.  
  11916.  
  11917.  
  11918.  
  11919.  
  11920.  
  11921.  
  11922.  
  11923.  
  11924.  
  11925.  
  11926.                                        Commands
  11927.                                        Page 185
  11928.  
  11929.  
  11930.  
  11931.  
  11932.  
  11933.  
  11934.  
  11935.                                   Q - PRO 4 Commands
  11936.  
  11937.  
  11938.      LPDETACH
  11939.      --------
  11940.      LPDETACH detaches the current user from the multiuser or LAN system printer
  11941.      or terminates the current spool file depending on the operating system. 
  11942.      This allows access to the printer by other users.
  11943.  
  11944.      Syntax:   LPDETACH
  11945.  
  11946.      Remarks        Failure to use this command when printing from Q-PRO 4 (not
  11947.                     the Report Generator) on some operating systems will lock
  11948.                     the print spooler until a system reset.  Operating systems
  11949.                     that do not use the command will ignore it.
  11950.  
  11951.  
  11952.  
  11953.  
  11954.  
  11955.  
  11956.  
  11957.  
  11958.  
  11959.  
  11960.  
  11961.  
  11962.  
  11963.  
  11964.  
  11965.  
  11966.  
  11967.  
  11968.  
  11969.  
  11970.  
  11971.  
  11972.  
  11973.  
  11974.  
  11975.  
  11976.  
  11977.  
  11978.  
  11979.  
  11980.  
  11981.  
  11982.  
  11983.  
  11984.  
  11985.  
  11986.                                        Commands
  11987.                                        Page 186
  11988.  
  11989.  
  11990.  
  11991.  
  11992.  
  11993.  
  11994.  
  11995.                                   Q - PRO 4 Commands
  11996.  
  11997.  
  11998.      LRETRY
  11999.      ------
  12000.      LRETRY sets the retry count for header record locking on multiuser systems.
  12001.  
  12002.      Syntax:   LRETRY <numeric data item>
  12003.  
  12004.      numeric data item        Any numeric data item.
  12005.      Remarks                  It is usually used in PROC LOAD.
  12006.  
  12007.      Example:
  12008.           LRETRY  100
  12009.  
  12010.  
  12011.  
  12012.  
  12013.  
  12014.  
  12015.  
  12016.  
  12017.  
  12018.  
  12019.  
  12020.  
  12021.  
  12022.  
  12023.  
  12024.  
  12025.  
  12026.  
  12027.  
  12028.  
  12029.  
  12030.  
  12031.  
  12032.  
  12033.  
  12034.  
  12035.  
  12036.  
  12037.  
  12038.  
  12039.  
  12040.  
  12041.  
  12042.  
  12043.  
  12044.  
  12045.  
  12046.                                        Commands
  12047.                                        Page 187
  12048.  
  12049.  
  12050.  
  12051.  
  12052.  
  12053.  
  12054.  
  12055.                                   Q - PRO 4 Commands
  12056.  
  12057.  
  12058.      MAKE
  12059.      ----
  12060.      MAKE deletes a file from the directory of a diskette (if it previously
  12061.      existed), and then creates it as directed by the parameters to the
  12062.      statement.  At creation a file number is assigned.  When the file is
  12063.      created, it is immediately ready for use.
  12064.  
  12065.      In all formats, the file name may be a string literal or string data item. 
  12066.      The error branch is taken if the system is unable to create the file (e.g.,
  12067.      write-protected or full disk). (Refer to the Programmer's Reference Manual
  12068.      for a full discussion of files.)  The statement may take one of four forms.
  12069.  
  12070.      Syntax 1: (Indexed and Random files)
  12071.  
  12072.      MAKE <filename> USING <FID filena> {INDEX <INDEX filena>}, <file num>
  12073.      {:error}
  12074.  
  12075.      filename       The name of the file as a literal in quotes or a string data
  12076.                     item.
  12077.      USING          Points to the FID file name.
  12078.      FID file name  The name of the FID file as a literal in quotes or a string
  12079.                     data item.
  12080.      INDEX          Points to the index file (indexed files only).  This phrase
  12081.                     is optional.  If omitted, an index file will be created that
  12082.                     is the same name as the FID file with the extension IDX.
  12083.      INDEX file na  The name of the INDEX file as a literal in quotes or a
  12084.                     string data item.
  12085.      file number    A literal or numeric data item.  Until closed or deleted,
  12086.                     the file will be referred to by this file number.
  12087.  
  12088.      Remarks        The FID (file item description file created by the FID
  12089.                     generator program) determines if the file is random or
  12090.                     indexed.  All additional information (file type, record
  12091.                     size, key size and location, etc.) is derived from
  12092.                     information in the FID file.
  12093.  
  12094.      Examples:
  12095.           MAKE "C:NEWDATA" USING "NEWDATA.FID", 1 :654
  12096.           MAKE #S0 USING #S1 INDEX #S3, #N1: 100
  12097.  
  12098.      Syntax 2: (Sequential Files)
  12099.  
  12100.           MAKE <filename>, <file type>, <file number> {<:error>}
  12101.  
  12102.      filename       The name of the file as a literal in quotes or a string data
  12103.                     item.
  12104.  
  12105.  
  12106.                                        Commands
  12107.                                        Page 188
  12108.  
  12109.  
  12110.  
  12111.  
  12112.  
  12113.  
  12114.  
  12115.                                   Q - PRO 4 Commands
  12116.  
  12117.  
  12118.      filetype       The type of sequential (text) file.  The file types are:
  12119.                     0    sequential output
  12120.                     1    sequential input
  12121.                     4    SDF (comma delimited) output
  12122.                     5    SDF (comma delimited) input
  12123.  
  12124.      file number    A literal or numeric data item.  Until closed or deleted,
  12125.                     the file will be referred to by this file number.
  12126.  
  12127.      Examples:
  12128.  
  12129.           MAKE "B:TEMP.$$$",1,1 :100
  12130.  
  12131.           LAN and Multiuser System Optional KEYWORD
  12132.           -----------------------------------------
  12133.           MAKE has an optional keyword after the file number, UNLOCKED.  If
  12134.           UNLOCKED is not used, a file is created in the locked mode.  
  12135.  
  12136.      Examples:
  12137.      MAKE "FILE" USING "FIDFILE",1 UNLOCKED :100
  12138.  
  12139.  
  12140.  
  12141.  
  12142.  
  12143.  
  12144.  
  12145.  
  12146.  
  12147.  
  12148.  
  12149.  
  12150.  
  12151.  
  12152.  
  12153.  
  12154.  
  12155.  
  12156.  
  12157.  
  12158.  
  12159.  
  12160.  
  12161.  
  12162.  
  12163.  
  12164.  
  12165.  
  12166.                                        Commands
  12167.                                        Page 189
  12168.  
  12169.  
  12170.  
  12171.  
  12172.  
  12173.  
  12174.  
  12175.                                   Q - PRO 4 Commands
  12176.  
  12177.  
  12178.      MEMEND
  12179.      MEMEND establishes the highest address in memory that Q-PRO 4 can use,
  12180.      presumably because machine language programs will be loaded at higher
  12181.      addresses.
  12182.  
  12183.      Syntax:
  12184.      MEMEND <address in decimal {:<error>}
  12185.  
  12186.      address in decimal       The address to be set.
  12187.      Remarks                  If the system would be left with insufficient
  12188.                               memory after changing the highest address used,
  12189.                               the error trap is taken with an Out2 OF MEMORY
  12190.                               error.
  12191.  
  12192.                               No particular restrictions apply to open files or
  12193.                               declared variables when MEMEND is invoked.
  12194.  
  12195.      Example:
  12196.           MEMEND 49152
  12197.  
  12198.  
  12199.  
  12200.  
  12201.  
  12202.  
  12203.  
  12204.  
  12205.  
  12206.  
  12207.  
  12208.  
  12209.  
  12210.  
  12211.  
  12212.  
  12213.  
  12214.  
  12215.  
  12216.  
  12217.  
  12218.  
  12219.  
  12220.  
  12221.  
  12222.  
  12223.  
  12224.  
  12225.  
  12226.                                        Commands
  12227.                                        Page 190
  12228.  
  12229.  
  12230.  
  12231.  
  12232.  
  12233.  
  12234.  
  12235.                                   Q - PRO 4 Commands
  12236.  
  12237.  
  12238.      MOVE
  12239.      ----
  12240.      The MOVE command is used to transfer data between data items.  Modifiers to
  12241.      the basic command provide powerful mechanisms for handling substrings, and
  12242.      concatenating data items.Data between Data Items
  12243.  
  12244.      Syntax:
  12245.  
  12246.      MOVE <dataitem1> {<string source modifier>} TO <dataitem2> {<string
  12247.      destination modifier>} {TRIMMED}
  12248.  
  12249.      dataitem1           The data items may be numeric or string literals, or
  12250.                          any string data item (data item 2 may not be a
  12251.                          literal).  MOVEing a string to a numeric data item is
  12252.                          acceptable if the string contains only numerically
  12253.                          acceptable data.
  12254.      string source
  12255.           modifier       The string source modifier provides a way to extract
  12256.                          substrings from a string data item.  The source data
  12257.                          item must be a string to use a modifier.  The format of
  12258.                          the source modifier is:
  12259.  
  12260.                          [start position,length or *]
  12261.  
  12262.  
  12263.                               The start position may range from 1 to the length
  12264.                               of the string.  The length may not exceed the
  12265.                               length of the string.  An asterisk (*) may be
  12266.                               substituted for the length of the string, in which
  12267.                               case the right-hand portion of the string from the
  12268.                               starting position on is taken.
  12269.  
  12270.                          string destination modifier
  12271.  
  12272.                               The string destination modifier allows the
  12273.                               placement of substrings within strings, or the
  12274.                               concatenation of strings.  The format of the
  12275.                               destination modifier is:
  12276.  
  12277.  
  12278.                          [start position or *]
  12279.  
  12280.                               The source string is moved to the start position
  12281.                               of the destination string.  If an asterisk is
  12282.                               used, the source string is appended to the
  12283.                               destination string.
  12284.  
  12285.  
  12286.                                        Commands
  12287.                                        Page 191
  12288.  
  12289.  
  12290.  
  12291.  
  12292.  
  12293.  
  12294.  
  12295.                                   Q - PRO 4 Commands
  12296.  
  12297.  
  12298.  
  12299.      TRIMMED             If the keyword TRIMMED is used, trailing spaces are
  12300.                          eliminated from the source string.
  12301.  
  12302.      Examples:
  12303.  
  12304.           Simple Moves
  12305.           ------------
  12306.           MOVE A TO B
  12307.                Moves field (or variable) "A" to field (or variable) "B". 
  12308.  
  12309.           MOVE 0 TO #N0 
  12310.                Moves the number zero (0) to numeric register 0, and clears it.
  12311.  
  12312.           MOVE "PLEASE ENTER A VALID ID CODE" TO STATUSMSG
  12313.                Moves "PLEASE ENTER A VALID ID CODE" to the field (or variable)
  12314.                STATUSMSG.
  12315.  
  12316.           Partial Moves
  12317.           -------------
  12318.           MOVE "     " TO #S0[3] 
  12319.                Moves 5 blanks to string register 0 beginning in position 3.
  12320.  
  12321.           MOVE NAME[1,10] TO FNAME
  12322.                Moves characters 1 through 10 in the field (or variable) NAME to
  12323.                the field (or variable) FNAME.
  12324.  
  12325.           MOVE #S0[#N0,FLDLEN] TO #S1[*]
  12326.                Moves the contents of string register 0 from the number in
  12327.                numeric register 0 for the length contained in FLDLEN.
  12328.  
  12329.  
  12330.           Move with Trimming
  12331.           ------------------
  12332.           MOVE #S3 TO #S3 TRIMMED
  12333.                Move #S3 to itself removing trailing blanks.
  12334.  
  12335.           MOVE $FIELD[#N0][1,20] TO #S[#N1][*] TRIMMED
  12336.                Moves a screen field with the offset contained in #N0 starting in
  12337.                position 1 for 20 characters to a string register whose number is
  12338.                contained in #N1.  The asterisk indicates that the previous data
  12339.                in the string register will be left intact and the new data will
  12340.                be concatenated.  The data moved will have trailing blanks
  12341.                dropped.
  12342.  
  12343.  
  12344.  
  12345.  
  12346.                                        Commands
  12347.                                        Page 192
  12348.  
  12349.  
  12350.  
  12351.  
  12352.  
  12353.  
  12354.  
  12355.                                   Q - PRO 4 Commands
  12356.  
  12357.  
  12358.           Concatenation (attach one string data item to another) 
  12359.           -------------
  12360.           MOVE #S0 TO #S1[*]
  12361.                Concatenates the contents of #S0 to the current contents of #S1.
  12362.  
  12363.           MOVE #S0 TO #S1[*] TRIMMED
  12364.                Truncates any trailing spaces in #S0 and then concatenates the
  12365.                contents of #S0 to the current contents of #S1.
  12366.  
  12367.  
  12368.  
  12369.  
  12370.  
  12371.  
  12372.  
  12373.  
  12374.  
  12375.  
  12376.  
  12377.  
  12378.  
  12379.  
  12380.  
  12381.  
  12382.  
  12383.  
  12384.  
  12385.  
  12386.  
  12387.  
  12388.  
  12389.  
  12390.  
  12391.  
  12392.  
  12393.  
  12394.  
  12395.  
  12396.  
  12397.  
  12398.  
  12399.  
  12400.  
  12401.  
  12402.  
  12403.  
  12404.  
  12405.  
  12406.                                        Commands
  12407.                                        Page 193
  12408.  
  12409.  
  12410.  
  12411.  
  12412.  
  12413.  
  12414.  
  12415.                                   Q - PRO 4 Commands
  12416.  
  12417.  
  12418.      MUL
  12419.      ---
  12420.      MUL multiplies two data items and optionally places the result in a third.
  12421.  
  12422.      Syntax:   MUL <data item 1> TIMES <data item 2>{GIVING <data item 3>}
  12423.  
  12424.      data item 1         The multiplier must be a valid numeric data item.  
  12425.      data item 2         The multiplicand must be a valid numeric data item.
  12426.      Remarks             If the GIVING clause is not present, then the result is
  12427.                          stored in data item 2.  Optionally, the keyword TIMES
  12428.                          may be replaced with a comma.
  12429.  
  12430.      Examples:
  12431.           MUL 1.5 TIMES REGPAY GIVING OTPAY
  12432.           MUL FACTOR , BASE
  12433.  
  12434.  
  12435.  
  12436.  
  12437.  
  12438.  
  12439.  
  12440.  
  12441.  
  12442.  
  12443.  
  12444.  
  12445.  
  12446.  
  12447.  
  12448.  
  12449.  
  12450.  
  12451.  
  12452.  
  12453.  
  12454.  
  12455.  
  12456.  
  12457.  
  12458.  
  12459.  
  12460.  
  12461.  
  12462.  
  12463.  
  12464.  
  12465.  
  12466.                                        Commands
  12467.                                        Page 194
  12468.  
  12469.  
  12470.  
  12471.  
  12472.  
  12473.  
  12474.  
  12475.                                   Q - PRO 4 Commands
  12476.  
  12477.  
  12478.      NCHECK
  12479.      ------
  12480.      The NCHECK statement will verify that a string data item contains only
  12481.      numeric data; i.e. no commas, dollar signs, or other trash.
  12482.  
  12483.      Syntax:   NCHECK <data item> {<:error>}
  12484.  
  12485.      data item      the string data item to be checked.
  12486.      error          The error branch is taken if the data item is not numeric. 
  12487.                     Note that a field of all spaces is considered numerically
  12488.                     valid (0).
  12489.  
  12490.      Examples:
  12491.           NCHECK $FIELD[#N0+3] :100
  12492.           NCHECK CUSTNUM[CUSTTYPE]  :1023
  12493.  
  12494.  
  12495.  
  12496.  
  12497.  
  12498.  
  12499.  
  12500.  
  12501.  
  12502.  
  12503.  
  12504.  
  12505.  
  12506.  
  12507.  
  12508.  
  12509.  
  12510.  
  12511.  
  12512.  
  12513.  
  12514.  
  12515.  
  12516.  
  12517.  
  12518.  
  12519.  
  12520.  
  12521.  
  12522.  
  12523.  
  12524.  
  12525.  
  12526.                                        Commands
  12527.                                        Page 195
  12528.  
  12529.  
  12530.  
  12531.  
  12532.  
  12533.  
  12534.  
  12535.                                   Q - PRO 4 Commands
  12536.  
  12537.  
  12538.      NEXT
  12539.      ----
  12540.      The NEXT statement moves the cursor to a specified field and returns
  12541.      control to the operator for data entry.
  12542.  
  12543.      Syntax:   NEXT <field name or *>
  12544.  
  12545.      field name or *     The name of the screen data field in quotes or a $FIELD
  12546.                          expression.  If the asterisk is used, the cursor will
  12547.                          move to the next sequential unlocked field.
  12548.      Remarks             It is the programmer's responsibility to insure that
  12549.                          NEXT does not jump control to a non-enterable screen
  12550.                          data field.  A NEXT command with no field specified
  12551.                          will move the cursor to the next enterable unlocked
  12552.                          field. 
  12553.  
  12554.      Examples:
  12555.           NEXT ALPHA
  12556.           NEXT $FIELD[#N1]
  12557.           NEXT *
  12558.           NEXT
  12559.  
  12560.  
  12561.  
  12562.  
  12563.  
  12564.  
  12565.  
  12566.  
  12567.  
  12568.  
  12569.  
  12570.  
  12571.  
  12572.  
  12573.  
  12574.  
  12575.  
  12576.  
  12577.  
  12578.  
  12579.  
  12580.  
  12581.  
  12582.  
  12583.  
  12584.  
  12585.  
  12586.                                        Commands
  12587.                                        Page 196
  12588.  
  12589.  
  12590.  
  12591.  
  12592.  
  12593.  
  12594.  
  12595.                                   Q - PRO 4 Commands
  12596.  
  12597.  
  12598.      NOFORMLOAD
  12599.      ----------
  12600.      NOFORMLOAD turns off the indicator set by the FORMLOAD command.  This means
  12601.      that after the NOFORMLOAD command is executed, a later return to the
  12602.      operating system will not cause the execution of the format builder
  12603.      utility.
  12604.  
  12605.      Syntax:   NOFORMLOAD
  12606.  
  12607.  
  12608.  
  12609.  
  12610.  
  12611.  
  12612.  
  12613.  
  12614.  
  12615.  
  12616.  
  12617.  
  12618.  
  12619.  
  12620.  
  12621.  
  12622.  
  12623.  
  12624.  
  12625.  
  12626.  
  12627.  
  12628.  
  12629.  
  12630.  
  12631.  
  12632.  
  12633.  
  12634.  
  12635.  
  12636.  
  12637.  
  12638.  
  12639.  
  12640.  
  12641.  
  12642.  
  12643.  
  12644.  
  12645.  
  12646.                                        Commands
  12647.                                        Page 197
  12648.  
  12649.  
  12650.  
  12651.  
  12652.  
  12653.  
  12654.  
  12655.                                   Q - PRO 4 Commands
  12656.  
  12657.  
  12658.      NOTRACE
  12659.      -------
  12660.      NOTRACE turns off the TRACE mode used for single-stepping through program
  12661.      statements.  Refer to the TRACE statement for an explanation of this mode.
  12662.  
  12663.      Syntax:   NOTRACE
  12664.  
  12665.  
  12666.  
  12667.  
  12668.  
  12669.  
  12670.  
  12671.  
  12672.  
  12673.  
  12674.  
  12675.  
  12676.  
  12677.  
  12678.  
  12679.  
  12680.  
  12681.  
  12682.  
  12683.  
  12684.  
  12685.  
  12686.  
  12687.  
  12688.  
  12689.  
  12690.  
  12691.  
  12692.  
  12693.  
  12694.  
  12695.  
  12696.  
  12697.  
  12698.  
  12699.  
  12700.  
  12701.  
  12702.  
  12703.  
  12704.  
  12705.  
  12706.                                        Commands
  12707.                                        Page 198
  12708.  
  12709.  
  12710.  
  12711.  
  12712.  
  12713.  
  12714.  
  12715.                                   Q - PRO 4 Commands
  12716.  
  12717.  
  12718.      OPEN
  12719.      ----
  12720.      OPEN locates a pre-existing file on disk and readies the file for I/O
  12721.      operations.
  12722.  
  12723.      Syntax 1: (Random and Indexed Files)
  12724.  
  12725.      OPEN <filena> USING <FID filena> {INDEX <index filena>},<file num> {:error}
  12726.  
  12727.      filena         The path and name of the file to be opened.  This may be a
  12728.                     literal or valid string data item.
  12729.      USING          Points the FID file to be used to open the file.
  12730.      FID filena     The path and name of the FID file (file item description
  12731.                     file created by the FID generator program).  When the file
  12732.                     was created, the FID determined if the file was to be random
  12733.                     or indexed.  All additional information (file type, record
  12734.                     size, key size and location, etc.) is derived from
  12735.                     information in the FID file.
  12736.      INDEX          If this phrase is used, the user must specifically designate
  12737.                     the INDEX file name and path.  If it is not used, the INDEX
  12738.                     file will be understood to be the same as the FID file with
  12739.                     the extension IDX.
  12740.      file num       The number that the file will be know by henceforth.
  12741.  
  12742.      Examples:
  12743.           OPEN "C:NEWDATA" USING "NEWDATA.FID", 1 :654
  12744.  
  12745.  
  12746.      Syntax 2: (Sequential Files)
  12747.  
  12748.      OPEN <filena>, <file type>, <file num> {<:error>}
  12749.  
  12750.      filena         The name of the file as a literal in quotes or a string data
  12751.                     item.
  12752.      filetype       The type of sequential (text) file.  The file types are:
  12753.                     0    sequential output
  12754.                     1    sequential input
  12755.                     4    SDF (comma delimited) output
  12756.                     5    SDF (comma delimited) input
  12757.  
  12758.      file num       A literal or numeric data item.  Until closed or deleted,
  12759.                     the file will be referred to by this file number.
  12760.  
  12761.      Examples:
  12762.           OPEN "B:TEMP.$$$",1,1 :100
  12763.  
  12764.  
  12765.  
  12766.                                        Commands
  12767.                                        Page 199
  12768.  
  12769.  
  12770.  
  12771.  
  12772.  
  12773.  
  12774.  
  12775.                                   Q - PRO 4 Commands
  12776.  
  12777.  
  12778.           Multiuser Optional Keywords
  12779.           ---------------------------
  12780.           OPEN has two optional keywords after the file number, UNLOCKED and R/O
  12781.           (read/only). By default, a file is opened as read/write and locked. 
  12782.           These keywords may be in any order and need not appear together.
  12783.  
  12784.      Examples:
  12785.           OPEN FILE USING FIDFILE,1 UNLOCKED R/O :100
  12786.           OPEN #S0,2,128,5 UNLOCKED
  12787.  
  12788.  
  12789.  
  12790.  
  12791.  
  12792.  
  12793.  
  12794.  
  12795.  
  12796.  
  12797.  
  12798.  
  12799.  
  12800.  
  12801.  
  12802.  
  12803.  
  12804.  
  12805.  
  12806.  
  12807.  
  12808.  
  12809.  
  12810.  
  12811.  
  12812.  
  12813.  
  12814.  
  12815.  
  12816.  
  12817.  
  12818.  
  12819.  
  12820.  
  12821.  
  12822.  
  12823.  
  12824.  
  12825.  
  12826.                                        Commands
  12827.                                        Page 200
  12828.  
  12829.  
  12830.  
  12831.  
  12832.  
  12833.  
  12834.  
  12835.                                   Q - PRO 4 Commands
  12836.  
  12837.  
  12838.      PEEK
  12839.      ----
  12840.      PEEK loads data into a string from memory.
  12841.  
  12842.      Syntax:   PEEK <decimal address>, <length>, <string>
  12843.  
  12844.      decimal address     Address to PEEK
  12845.      length              The length must be less than 256 characters.  On 16 bit
  12846.                          systems PEEK may be used in conjunction with DEFSEG.
  12847.      string              String data item to place the data in.  
  12848.  
  12849.      Examples:
  12850.           PEEK 49012, 6, #S0
  12851.           PEEK #N1,#N2,WHAT 
  12852.  
  12853.  
  12854.  
  12855.  
  12856.  
  12857.  
  12858.  
  12859.  
  12860.  
  12861.  
  12862.  
  12863.  
  12864.  
  12865.  
  12866.  
  12867.  
  12868.  
  12869.  
  12870.  
  12871.  
  12872.  
  12873.  
  12874.  
  12875.  
  12876.  
  12877.  
  12878.  
  12879.  
  12880.  
  12881.  
  12882.  
  12883.  
  12884.  
  12885.  
  12886.                                        Commands
  12887.                                        Page 201
  12888.  
  12889.  
  12890.  
  12891.  
  12892.  
  12893.  
  12894.  
  12895.                                   Q - PRO 4 Commands
  12896.  
  12897.  
  12898.      POKE
  12899.      ----
  12900.      POKE moves a string of data into memory.
  12901.  
  12902.      Syntax:   POKE <decimal address>, <string>
  12903.  
  12904.      decimal address     Address to POKE.  On 16 bit systems POKE may be used in
  12905.                          conjunction with DEFSEG.
  12906.      string              String data item which contains the data.  
  12907.  
  12908.      Examples:
  12909.           POKE 50234, &DESC[#N0]
  12910.           POKE #N1, #S1
  12911.  
  12912.  
  12913.  
  12914.  
  12915.  
  12916.  
  12917.  
  12918.  
  12919.  
  12920.  
  12921.  
  12922.  
  12923.  
  12924.  
  12925.  
  12926.  
  12927.  
  12928.  
  12929.  
  12930.  
  12931.  
  12932.  
  12933.  
  12934.  
  12935.  
  12936.  
  12937.  
  12938.  
  12939.  
  12940.  
  12941.  
  12942.  
  12943.  
  12944.  
  12945.  
  12946.                                        Commands
  12947.                                        Page 202
  12948.  
  12949.  
  12950.  
  12951.  
  12952.  
  12953.  
  12954.  
  12955.                                   Q - PRO 4 Commands
  12956.  
  12957.  
  12958.      POSN
  12959.      ----
  12960.      POSN is used to access an indexed file by its key or a random file by its
  12961.      record number. 
  12962.  
  12963.      Syntax 1:
  12964.  
  12965.      POSN <file number> TO <record number/key> {RELATIVE} {:error}
  12966.  
  12967.      file number         The file number must be an open random or indexed file.
  12968.      record number/key   If the file is a random file, then it must be
  12969.                          positioned to a numeric record number (i.e., numeric
  12970.                          data item).  If the file is indexed, then it must be
  12971.                          positioned to a string value (literal or string data
  12972.                          item).  Remember: keys in indexed files are ASCII
  12973.                          strings.  If the string is not the same length as the
  12974.                          defined key field of the file, then it is padded out to
  12975.                          the right for key search purposes.  Similarly, if the
  12976.                          string is longer than the key field, it is truncated on
  12977.                          the right.
  12978.      RELATIVE            If the key is not found and the keyword RELATIVE is
  12979.                          given, then an indexed file is left positioned at the
  12980.                          next key higher than the one given.  Otherwise, the
  12981.                          file is left positioned at the end.
  12982.      error               No error is generated if the position requested is in-
  12983.                          valid (i.e., off the end of the file, or the given key
  12984.                          does not exist.) Such an error would be detected at the
  12985.                          time of the following read or write statement.
  12986.  
  12987.                          Errors generated by this statement pertain to the
  12988.                          validity of the type of key given for the file type
  12989.                          (e.g., a string key for a random file).
  12990.  
  12991.      Remarks             For indexed files, the POSN statement need not be used
  12992.                          to arrive at a specific key for a write statement, as
  12993.                          the key to be written is implicit in the data record. 
  12994.                          Such a POSN statement is automatically done before an
  12995.                          indexed write.
  12996.  
  12997.      Examples:
  12998.           POSN 1 TO 5 :100
  12999.           POSN 3 TO "*SYSTEM*" RELATIVE
  13000.           POSN 1 TO #N0
  13001.           POSN 99 TO RECNO
  13002.  
  13003.       
  13004.  
  13005.  
  13006.                                        Commands
  13007.                                        Page 203
  13008.  
  13009.  
  13010.  
  13011.  
  13012.  
  13013.  
  13014.  
  13015.                                   Q - PRO 4 Commands
  13016.  
  13017.  
  13018.  
  13019.      POSN, with the optional modifier, USING, will also change the current key.
  13020.  
  13021.      Syntax 2: (Change keys and position)
  13022.  
  13023.      POSN <file number> TO <key> {USING <key #> {:error}
  13024.  
  13025.      Remarks        Identical in function to POSN with the added capability of
  13026.                     changing the current key of an indexed file.
  13027.         
  13028.      Examples:
  13029.           POSN 1 TO &KEY[2] USING #N2 
  13030.  
  13031.  
  13032.  
  13033.  
  13034.  
  13035.  
  13036.  
  13037.  
  13038.  
  13039.  
  13040.  
  13041.  
  13042.  
  13043.  
  13044.  
  13045.  
  13046.  
  13047.  
  13048.  
  13049.  
  13050.  
  13051.  
  13052.  
  13053.  
  13054.  
  13055.  
  13056.  
  13057.  
  13058.  
  13059.  
  13060.  
  13061.  
  13062.  
  13063.  
  13064.  
  13065.  
  13066.                                        Commands
  13067.                                        Page 204
  13068.  
  13069.  
  13070.  
  13071.  
  13072.  
  13073.  
  13074.  
  13075.                                   Q - PRO 4 Commands
  13076.  
  13077.  
  13078.      PRINT
  13079.      -----
  13080.      PRINT allows the program to issue data directly to the screen at the
  13081.      current cursor position.
  13082.  
  13083.      It is most often used in conjunction with CURSOR.
  13084.  
  13085.      Syntax:   PRINT <value> {, <value>, <value> . . .}
  13086.  
  13087.      value          A value may be any numeric or string data item.  Numeric
  13088.                     values are issued to the screen as ASCII strings (use @ to
  13089.                     generate control codes).  For example, if the sequence ESC
  13090.                     (decimal 27) followed by ")" turns on an unconfigured
  13091.                     highlight, and ESC "(" turns it off, we could place a
  13092.                     highlighted message at the top of the screen as follows:
  13093.  
  13094.                     CURSOR 0,0
  13095.                     PRINT @27,')','THIS IS A TEST',@27,'('
  13096.  
  13097.      Remarks        The data displayed via the PRINT command will not be sent to
  13098.                     the printer via the PRINTSCN command.  Data displayed with
  13099.                     the PRINT command on the screen will not be restored after a
  13100.                     HELP or DEBUG command is executed.
  13101.  
  13102.  
  13103.  
  13104.  
  13105.  
  13106.  
  13107.  
  13108.  
  13109.  
  13110.  
  13111.  
  13112.  
  13113.  
  13114.  
  13115.  
  13116.  
  13117.  
  13118.  
  13119.  
  13120.  
  13121.  
  13122.  
  13123.  
  13124.  
  13125.  
  13126.                                        Commands
  13127.                                        Page 205
  13128.  
  13129.  
  13130.  
  13131.  
  13132.  
  13133.  
  13134.  
  13135.                                   Q - PRO 4 Commands
  13136.  
  13137.  
  13138.      PRINTSCN
  13139.      --------
  13140.      PRINTSCN dumps the current contents of the screen to the list device
  13141.      exactly as seen on the screen.
  13142.  
  13143.      Syntax:   PRINTSCN
  13144.  
  13145.  
  13146.  
  13147.  
  13148.  
  13149.  
  13150.  
  13151.  
  13152.  
  13153.  
  13154.  
  13155.  
  13156.  
  13157.  
  13158.  
  13159.  
  13160.  
  13161.  
  13162.  
  13163.  
  13164.  
  13165.  
  13166.  
  13167.  
  13168.  
  13169.  
  13170.  
  13171.  
  13172.  
  13173.  
  13174.  
  13175.  
  13176.  
  13177.  
  13178.  
  13179.  
  13180.  
  13181.  
  13182.  
  13183.  
  13184.  
  13185.  
  13186.                                        Commands
  13187.                                        Page 206
  13188.  
  13189.  
  13190.  
  13191.  
  13192.  
  13193.  
  13194.  
  13195.                                   Q - PRO 4 Commands
  13196.  
  13197.  
  13198.      PROC
  13199.      ----
  13200.      The PROC statement, although not an executable statement as such, is an
  13201.      important part of the command structure.  Its presence in a program denotes
  13202.      the start of a procedure.
  13203.  
  13204.      Syntax:
  13205.  
  13206.      PROC <procedure name>
  13207.  
  13208.      procedure name      This must be a literal that is not in quotes.  All
  13209.                          naming conventions apply.  See Programmer's Reference
  13210.                          Guide for more detail.
  13211.  
  13212.      Examples:
  13213.           PROC ERROR
  13214.           PROC CUSTNOP
  13215.  
  13216.  
  13217.  
  13218.  
  13219.  
  13220.  
  13221.  
  13222.  
  13223.  
  13224.  
  13225.  
  13226.  
  13227.  
  13228.  
  13229.  
  13230.  
  13231.  
  13232.  
  13233.  
  13234.  
  13235.  
  13236.  
  13237.  
  13238.  
  13239.  
  13240.  
  13241.  
  13242.  
  13243.  
  13244.  
  13245.  
  13246.                                        Commands
  13247.                                        Page 207
  13248.  
  13249.  
  13250.  
  13251.  
  13252.  
  13253.  
  13254.  
  13255.                                   Q - PRO 4 Commands
  13256.  
  13257.  
  13258.      PUT
  13259.      ---
  13260.      PUT transfers a data item to a file buffer or printer buffer for later
  13261.      output to the file or printer.
  13262.  
  13263.      Syntax:   PUT <data item or *> TO <file number> {FOR <length>} {:error}
  13264.  
  13265.      data item or *      Any data item may be used.  If the data item is an
  13266.                          asterisk (*), then all enterable, unlocked fields on
  13267.                          the screen are moved to the file buffer, in the order
  13268.                          they appear on the screen, starting with the first
  13269.                          unprotected field on the screen.  The FOR clause is not
  13270.                          used here.
  13271.      TO                  Points to the file number designator
  13272.      file number         A valid open file.  Using a file number of 0 denotes
  13273.                          that the output is to be sent to the system list
  13274.                          device, instead of a disk file.
  13275.      FOR                 If the FOR clause is not given, then the data is output
  13276.                          for the full number of character positions it currently
  13277.                          occupies.  The FOR clause may be used to place blank
  13278.                          padding on the right, or to truncate the data item, as
  13279.                          appropriate.
  13280.      Remarks             PUT is not used when FID file data is being used.  A
  13281.                          special type of data item may be used to output control
  13282.                          characters to the file.  An at sign (@) denotes that
  13283.                          the following literal value is a control character to
  13284.                          be output.  This is useful when building files to be
  13285.                          later transmitted to a remote computer, or when using
  13286.                          special features of a printer.
  13287.  
  13288.                          For SDF files, all fields are output enclosed within
  13289.                          quotes and separated by commas.
  13290.  
  13291.      Examples:
  13292.           PUT PRODNUM TO 1
  13293.           PUT @09 TO 0
  13294.           PUT " " TO 0 FOR 10
  13295.           PUT #S0 TO 5  :1000
  13296.  
  13297.  
  13298.  
  13299.  
  13300.  
  13301.  
  13302.  
  13303.  
  13304.  
  13305.  
  13306.                                        Commands
  13307.                                        Page 208
  13308.  
  13309.  
  13310.  
  13311.  
  13312.  
  13313.  
  13314.  
  13315.                                   Q - PRO 4 Commands
  13316.  
  13317.  
  13318.      RCLEAR
  13319.      ------
  13320.      RCLEAR clears the record buffer to spaces and resets the buffer pointer.
  13321.  
  13322.      Syntax:   RCLEAR <file number> 
  13323.  
  13324.      file number         The file number of an open indexed or random file.
  13325.      Remarks             This command is not used with sequential files.
  13326.  
  13327.  
  13328.       
  13329.  
  13330.  
  13331.  
  13332.  
  13333.  
  13334.  
  13335.  
  13336.  
  13337.  
  13338.  
  13339.  
  13340.  
  13341.  
  13342.  
  13343.  
  13344.  
  13345.  
  13346.  
  13347.  
  13348.  
  13349.  
  13350.  
  13351.  
  13352.  
  13353.  
  13354.  
  13355.  
  13356.  
  13357.  
  13358.  
  13359.  
  13360.  
  13361.  
  13362.  
  13363.  
  13364.  
  13365.  
  13366.                                        Commands
  13367.                                        Page 209
  13368.  
  13369.  
  13370.  
  13371.  
  13372.  
  13373.  
  13374.  
  13375.                                   Q - PRO 4 Commands
  13376.  
  13377.  
  13378.      READ
  13379.      ----
  13380.      The READ command is used to access data records within a file.
  13381.  
  13382.      Syntax:   READ <file number> {NOADV} {:error}
  13383.  
  13384.      file number         If the file number pertains to a sequential input file,
  13385.                          then the file is advanced until a carriage return/line
  13386.                          feed sequence is bypassed.  The file is positioned at
  13387.                          the start of a new record, ready for GET statements.
  13388.  
  13389.                          For random or indexed files, the file buffer is loaded
  13390.                          with a new record, the fields of which can then be
  13391.                          accessed by referring to FID fields or with GET
  13392.                          statements.
  13393.      NOADV               If the NOADV keyword is given, the file is remains
  13394.                          positioned at the same record just read.  Otherwise,
  13395.                          the file position is incremented to point to the next
  13396.                          record in the file (applies to random and indexed files
  13397.                          only).  Using NOADV whenever possible will provide
  13398.                          optimal record access time.
  13399.      error               Errors are generated if there is an attempt to go past
  13400.                          the end of a file, or to access a record with a
  13401.                          non-existent key.
  13402.  
  13403.      Examples:
  13404.           READ 3 :1000
  13405.           READ 5 NOADV
  13406.  
  13407.  
  13408.  
  13409.      RENAME
  13410.      ------
  13411.      RENAME changes the name of a file.
  13412.  
  13413.      Syntax:   RENAME <old file name>, <new file name> {:error}
  13414.  
  13415.      old file name       The name of the file to be renamed.
  13416.      new file name       The new file name.
  13417.      error               An error occurs if the old file name is non-existent,
  13418.                          or if the new file name already exists.
  13419.      Remarks             The renamed file MUST NOT be open at the time of
  13420.                          renaming. 
  13421.  
  13422.      Examples:
  13423.           RENAME "B:TEMP.DAT","MASTER.DAT"
  13424.  
  13425.  
  13426.                                        Commands
  13427.                                        Page 210
  13428.  
  13429.  
  13430.  
  13431.  
  13432.  
  13433.  
  13434.  
  13435.                                   Q - PRO 4 Commands
  13436.  
  13437.  
  13438.           RENAME #S0,$FIELD[#N9]  :1013
  13439.      RESET
  13440.      -----
  13441.      RESET clears a Boolean flag register.  Refer to the IF statement for the
  13442.      use of Boolean registers in conditional statements.
  13443.  
  13444.      Syntax:   RESET <flag register>
  13445.  
  13446.      flag register       Any of the Boolean or flag registers from #B0 to #B9.
  13447.  
  13448.      Example:
  13449.           RESET #B4
  13450.  
  13451.  
  13452.  
  13453.  
  13454.  
  13455.  
  13456.  
  13457.  
  13458.  
  13459.  
  13460.  
  13461.  
  13462.  
  13463.  
  13464.  
  13465.  
  13466.  
  13467.  
  13468.  
  13469.  
  13470.  
  13471.  
  13472.  
  13473.  
  13474.  
  13475.  
  13476.  
  13477.  
  13478.  
  13479.  
  13480.  
  13481.  
  13482.  
  13483.  
  13484.  
  13485.  
  13486.                                        Commands
  13487.                                        Page 211
  13488.  
  13489.  
  13490.  
  13491.  
  13492.  
  13493.  
  13494.  
  13495.                                   Q - PRO 4 Commands
  13496.  
  13497.  
  13498.      RESTART
  13499.      -------
  13500.      RESTART places the file buffer pointer (moved across a file buffer by
  13501.      repeated GET or PUT statements) to an arbitrary position within a file
  13502.      buffer (does not apply to sequential files).
  13503.  
  13504.      Syntax:   RESTART <file number> {TO <position>}  {:error}
  13505.  
  13506.      file number         The number of the file to be restarted.  If the file
  13507.                          number is 0, then a form feed is issued to the list
  13508.                          device, and the position value (if any) is used to
  13509.                          space down the next page.  The page number register
  13510.                          (#P) is incremented, and the line number register (#L)
  13511.                          is set to the number of lines skipped on the new page
  13512.                          (default 0).
  13513.      position            The position within the record to move the pointer to.
  13514.      Remarks             The default value for pointer placement (taken when the
  13515.                          TO phrase is not given) is the start of the file
  13516.                          buffer.
  13517.  
  13518.      Examples:
  13519.           RESTART 0
  13520.           RESTART 1 TO 25
  13521.           RESTART 89
  13522.  
  13523.  
  13524.  
  13525.  
  13526.  
  13527.  
  13528.  
  13529.  
  13530.  
  13531.  
  13532.  
  13533.  
  13534.  
  13535.  
  13536.  
  13537.  
  13538.  
  13539.  
  13540.  
  13541.  
  13542.  
  13543.  
  13544.  
  13545.  
  13546.                                        Commands
  13547.                                        Page 212
  13548.  
  13549.  
  13550.  
  13551.  
  13552.  
  13553.  
  13554.  
  13555.                                   Q - PRO 4 Commands
  13556.  
  13557.  
  13558.      RESUME
  13559.      ------
  13560.      RESUME gives control back to the operator in the current screen data field.
  13561.  
  13562.      Syntax:   RESUME
  13563.  
  13564.  
  13565.  
  13566.  
  13567.  
  13568.  
  13569.  
  13570.  
  13571.  
  13572.  
  13573.  
  13574.  
  13575.  
  13576.  
  13577.  
  13578.  
  13579.  
  13580.  
  13581.  
  13582.  
  13583.  
  13584.  
  13585.  
  13586.  
  13587.  
  13588.  
  13589.  
  13590.  
  13591.  
  13592.  
  13593.  
  13594.  
  13595.  
  13596.  
  13597.  
  13598.  
  13599.  
  13600.  
  13601.  
  13602.  
  13603.  
  13604.  
  13605.  
  13606.                                        Commands
  13607.                                        Page 213
  13608.  
  13609.  
  13610.  
  13611.  
  13612.  
  13613.  
  13614.  
  13615.                                   Q - PRO 4 Commands
  13616.  
  13617.  
  13618.      RETURN
  13619.      ------
  13620.      RETURN gives programmatic control back to a calling procedure.  Each RETURN
  13621.      executed must be matched by a previous CALL statement.  It is possible,
  13622.      however, to exit from a FOR/ENDFOR loop to return to a calling statement
  13623.      (by executing a RETURN) with no ill effects.
  13624.  
  13625.      Syntax:   RETURN
  13626.        
  13627.      Examples:
  13628.           IF #N1 = 5 RETURN
  13629.           RETURN
  13630.  
  13631.  
  13632.  
  13633.  
  13634.  
  13635.  
  13636.  
  13637.  
  13638.  
  13639.  
  13640.  
  13641.  
  13642.  
  13643.  
  13644.  
  13645.  
  13646.  
  13647.  
  13648.  
  13649.  
  13650.  
  13651.  
  13652.  
  13653.  
  13654.  
  13655.  
  13656.  
  13657.  
  13658.  
  13659.  
  13660.  
  13661.  
  13662.  
  13663.  
  13664.  
  13665.  
  13666.                                        Commands
  13667.                                        Page 214
  13668.  
  13669.  
  13670.  
  13671.  
  13672.  
  13673.  
  13674.  
  13675.                                   Q - PRO 4 Commands
  13676.  
  13677.  
  13678.      RJUST
  13679.      -----
  13680.      RJUST right justifies data in any data item.
  13681.  
  13682.      Syntax:   RJUST <data item>
  13683.            
  13684.      data item      The data item in which data is to be right justified.
  13685.  
  13686.      Example:
  13687.           RJUST #S1
  13688.       
  13689.  
  13690.  
  13691.  
  13692.  
  13693.  
  13694.  
  13695.  
  13696.  
  13697.  
  13698.  
  13699.  
  13700.  
  13701.  
  13702.  
  13703.  
  13704.  
  13705.  
  13706.  
  13707.  
  13708.  
  13709.  
  13710.  
  13711.  
  13712.  
  13713.  
  13714.  
  13715.  
  13716.  
  13717.  
  13718.  
  13719.  
  13720.  
  13721.  
  13722.  
  13723.  
  13724.  
  13725.  
  13726.                                        Commands
  13727.                                        Page 215
  13728.  
  13729.  
  13730.  
  13731.  
  13732.  
  13733.  
  13734.  
  13735.                                   Q - PRO 4 Commands
  13736.  
  13737.  
  13738.      RLOCK
  13739.      -----
  13740.      On LANs and multiuser systems RLOCK marks the data record where the file is
  13741.      currently positioned as being locked.
  13742.  
  13743.      Syntax:   RLOCK <file number> {:error}
  13744.  
  13745.      file number         The file number of the record to be locked.
  13746.      error               If the record is marked as locked, presumably by
  13747.                          another user using the RLOCK command, a branch will be
  13748.                          taken to the error label.
  13749.      Remarks             The record locked is the one currently being pointed to
  13750.                          by the file pointer.  Thus these two command sequences
  13751.                          are the same:
  13752.  
  13753.                          POSN 1 TO #S0       POSN 1 TO #S0
  13754.                          RLOCK 1:LOCKED      READ 1 NOADV
  13755.                          READ 1              RLOCK 1:LOCKED
  13756.  
  13757.  
  13758.                          At NO TIME is the record physically locked.  As it is
  13759.                          always available to the programmer, it is up to the
  13760.                          programmer to take the appropriate action for the
  13761.                          application.  RLOCK is ignored by operating systems
  13762.                          that are not multiuser.  RLOCK is always used in
  13763.                          conjunction with RUNLOCK.
  13764.  
  13765.  
  13766.                          If a record is locked in a file, another RLOCK command
  13767.                          will unlock the previously locked record as well as
  13768.                          lock the current record.  Refer to the Programmer's
  13769.                          Reference Manual for more detail.
  13770.  
  13771.      Example
  13772.           RLOCK 1: 100
  13773.           RLOCK #N1:100
  13774.  
  13775.  
  13776.  
  13777.  
  13778.  
  13779.  
  13780.  
  13781.  
  13782.  
  13783.  
  13784.  
  13785.  
  13786.                                        Commands
  13787.                                        Page 216
  13788.  
  13789.  
  13790.  
  13791.  
  13792.  
  13793.  
  13794.  
  13795.                                   Q - PRO 4 Commands
  13796.  
  13797.  
  13798.      ROUND
  13799.      -----
  13800.      ROUND is used to round a numeric quantity to some significant number of
  13801.      digits.
  13802.  
  13803.      Syntax:   ROUND <data item 1> BY <size> INTO <data item 2>
  13804.  
  13805.      data item 1         Data item 1 (which must be numeric) will be rounded off
  13806.                          to the indicated number of significant fractional
  13807.                          digits.
  13808.      data item 2         The result will be placed into data item 2.
  13809.  
  13810.      Example:
  13811.           ROUND #N0 BY 2 INTO AVERAGE
  13812.           ROUND SUM BY SIGNIF INTO SUM
  13813.  
  13814.  
  13815.  
  13816.  
  13817.  
  13818.  
  13819.  
  13820.  
  13821.  
  13822.  
  13823.  
  13824.  
  13825.  
  13826.  
  13827.  
  13828.  
  13829.  
  13830.  
  13831.  
  13832.  
  13833.  
  13834.  
  13835.  
  13836.  
  13837.  
  13838.  
  13839.  
  13840.  
  13841.  
  13842.  
  13843.  
  13844.  
  13845.  
  13846.                                        Commands
  13847.                                        Page 217
  13848.  
  13849.  
  13850.  
  13851.  
  13852.  
  13853.  
  13854.  
  13855.                                   Q - PRO 4 Commands
  13856.  
  13857.  
  13858.      RUN
  13859.      ---
  13860.      The RUN command executes another program directly from Q-PRO 4,  and
  13861.      (normally) returns to the same format file when the loaded program is done.
  13862.  
  13863.      Syntax:   RUN <program name> USING <parameter string> {NORETURN} {NOPAUSE}
  13864.      {RELOAD <name>} {:error}
  13865.  
  13866.      program name        The program named may be a literal or string data item
  13867.                          containing the name of any valid program.
  13868.      parameter string    The parameter string is a literal or string data item
  13869.                          which contains whatever parameters the program would be
  13870.                          given if executed from the system command level.  If
  13871.                          there is NO PARAMETER to be passed, then a null
  13872.                          argument should be used.
  13873.      Remarks             RUN permits the re-execution of Q-PRO 4 automatically. 
  13874.                          As control is turned over to another executable
  13875.                          program, any working values that the current Q-PRO4
  13876.                          application program was using (such as registers,
  13877.                          variables, etc) will be lost.  Files are automatically
  13878.                          closed.
  13879.  
  13880.           Keywords
  13881.           --------
  13882.  
  13883.           NORETURN       Q-PRO 4 is not re-executed upon completion of the
  13884.                          loaded program.
  13885.           NOPAUSE        Control will return to Q-PRO 4 without operator
  13886.                          intervention.
  13887.  
  13888.           RELOAD<file>   Control will go to the named Q-PRO 4 filename.
  13889.  
  13890.  
  13891.      Examples:
  13892.           RUN "WORDSTAR.EXE" USING "LETTERS.DAT"
  13893.           RUN "PIP.COM" USING "B:OLD=B:NEW" NORETURN
  13894.           RUN "REPORT.CMD" USING #S1
  13895.           RUN "\COMMAND.COM" USING "/C COPY \DATA\CUSTOMER.DAT
  13896.                \BACKUP\CUSTOMER.DAT" RELOAD "MENU.QNE"
  13897.           RUN "WORDSTAR.EXE" USING "" 
  13898.  
  13899.  
  13900.  
  13901.  
  13902.  
  13903.  
  13904.  
  13905.  
  13906.                                        Commands
  13907.                                        Page 218
  13908.  
  13909.  
  13910.  
  13911.  
  13912.  
  13913.  
  13914.  
  13915.                                   Q - PRO 4 Commands
  13916.  
  13917.  
  13918.      RUNLOCK
  13919.      -------
  13920.      On a LAN or multiuser operating system RUNLOCK unlocks the record currently
  13921.      marked as locked for a file.
  13922.  
  13923.      Syntax:   RUNLOCK <file number> {:error}
  13924.  
  13925.      file number         The file number, a literal or string data item, which
  13926.                          is to have the record unlocked.
  13927.  
  13928.      Remarks             RUNLOCK is ignored if there is no locked record. 
  13929.                          RUNLOCK is always used in conjunction with RLOCK.
  13930.  
  13931.      Example:
  13932.           RUNLOCK 1100
  13933.  
  13934.  
  13935.  
  13936.  
  13937.  
  13938.  
  13939.  
  13940.  
  13941.  
  13942.  
  13943.  
  13944.  
  13945.  
  13946.  
  13947.  
  13948.  
  13949.  
  13950.  
  13951.  
  13952.  
  13953.  
  13954.  
  13955.  
  13956.  
  13957.  
  13958.  
  13959.  
  13960.  
  13961.  
  13962.  
  13963.  
  13964.  
  13965.  
  13966.                                        Commands
  13967.                                        Page 219
  13968.  
  13969.  
  13970.  
  13971.  
  13972.  
  13973.  
  13974.  
  13975.                                   Q - PRO 4 Commands
  13976.  
  13977.  
  13978.      SECURE
  13979.      ------
  13980.      Use of SECURE in conjunction with WRITE or FREE will guard against loss of
  13981.      data because of power loss, etc.
  13982.  
  13983.      The price of safety is extra time spent updating the file (one sector read,
  13984.      one sector written) and updating the system directory for the disk on which
  13985.      the file is located.
  13986.  
  13987.      Syntax:   SECURE <file number> {:error}
  13988.  
  13989.      file number         The file number to be secured.
  13990.      Remarks             SECURE has no effect on sequential or random files.
  13991.  
  13992.      Example:
  13993.           SECURE 1
  13994.           SECURE #N[FILENO]SET
  13995.  
  13996.  
  13997.      SET
  13998.      ---
  13999.      SET sets or turns on a Boolean or flag register.
  14000.  
  14001.      Syntax:   SET <Boolean register>
  14002.  
  14003.      Boolean register    The register number from #B0 to #B9.
  14004.      Remarks             Refer to the IF statement for the use of Boolean
  14005.                          registers in conditional statements.
  14006.  
  14007.      Example:
  14008.           SET #B0
  14009.           SET #B9
  14010.  
  14011.  
  14012.  
  14013.  
  14014.  
  14015.  
  14016.  
  14017.  
  14018.  
  14019.  
  14020.  
  14021.  
  14022.  
  14023.  
  14024.  
  14025.  
  14026.                                        Commands
  14027.                                        Page 220
  14028.  
  14029.  
  14030.  
  14031.  
  14032.  
  14033.  
  14034.  
  14035.                                   Q - PRO 4 Commands
  14036.  
  14037.  
  14038.      SETDATE
  14039.      -------
  14040.      SETDATE sets the system date.
  14041.  
  14042.      Syntax:   SETDATE <date string>
  14043.  
  14044.      date string         The date to set the system to as a literal or valid
  14045.                          string data item of the format:
  14046.  
  14047.                               MM/DD/YYYY hh:mm:ss
  14048.  
  14049.                               MM = MONTH     hh = hours
  14050.                               DD = DAY       mm = minutes
  14051.                               YYYY = YEAR    ss = seconds
  14052.  
  14053.      Remarks             On PCDOS and MSDOS this will set the system date.  On
  14054.                          all others, the date will be stored in a system
  14055.                          register for later use.  The register will be preserved
  14056.                          across CHAINs (BUT NOT RUNs).  A literal or string data
  14057.                          item may be used.  Refer also to GETDATE.
  14058.  
  14059.      Examples:
  14060.           SETDATE "08/31/1987 11:23:45"
  14061.           SETDATE #S1
  14062.  
  14063.  
  14064.  
  14065.      SIZE
  14066.      ----
  14067.      SIZE computes the length of a string data item.
  14068.  
  14069.      Syntax:   SIZE <data item 1> INTO <data item 2> {TRIMMED}
  14070.  
  14071.      data item 1         Data item 1 is the string register, field, or variable
  14072.                          to be sized.
  14073.      data item 2         Data item 2 is the numeric register, field, or variable
  14074.                          into which the size should be placed.
  14075.      Remarks             Note that unlike string registers, fields and variables
  14076.                          will always give the same result unless the TRIMMED
  14077.                          form is used to drop trailing spaces, since by nature
  14078.                          fields and variables are of fixed length.
  14079.  
  14080.      Example:
  14081.           SIZE #S0 INTO #N0
  14082.           SIZE APPLE INTO WATERMELON TRIMMED
  14083.  
  14084.  
  14085.  
  14086.                                        Commands
  14087.                                        Page 221
  14088.  
  14089.  
  14090.  
  14091.  
  14092.  
  14093.  
  14094.  
  14095.                                   Q - PRO 4 Commands
  14096.  
  14097.  
  14098.      SUB
  14099.      ---
  14100.      SUB subtracts one numeric data item from another and, optionally, leaves
  14101.      the result in a third.
  14102.  
  14103.      Syntax:   SUB <dataitem1> FROM <dataitem2> {GIVING <dataitem3>}
  14104.  
  14105.      dataitem1           The number or numeric data item to be subtracted.
  14106.      dataitem2           The numeric data item to be subtracted from.
  14107.      GIVING              If the GIVING clause is not present, then the result is
  14108.                          stored in data item 2.
  14109.      Remarks             The keyword FROM may be replaced by a comma.
  14110.  
  14111.      Example:
  14112.           SUB 5 FROM RESULT GIVING NEWRES
  14113.           SUB 1 FROM COUNT
  14114.           SUB #N0 FROM #N1 GIVING #N2
  14115.  
  14116.  
  14117.  
  14118.  
  14119.  
  14120.  
  14121.  
  14122.  
  14123.  
  14124.  
  14125.  
  14126.  
  14127.  
  14128.  
  14129.  
  14130.  
  14131.  
  14132.  
  14133.  
  14134.  
  14135.  
  14136.  
  14137.  
  14138.  
  14139.  
  14140.  
  14141.  
  14142.  
  14143.  
  14144.  
  14145.  
  14146.                                        Commands
  14147.                                        Page 222
  14148.  
  14149.  
  14150.  
  14151.  
  14152.  
  14153.  
  14154.  
  14155.                                   Q - PRO 4 Commands
  14156.  
  14157.  
  14158.      SYSMODE
  14159.      -------
  14160.      SYSMODE is a system initiating command.  It has two modifiers:
  14161.  
  14162.      Syntax 1:      SYSMODE BTAB <SET or RESET>
  14163.  
  14164.      SET            SYSMODE BTAB SET specifies that a proc in a screen data
  14165.                     field that the cursor is backtabbed out of is always
  14166.                     executed.
  14167.      RESET          SYSMODE BTAB RESET specifies that a proc is not executed if
  14168.                     there is no data (default mode) in the screen data field and
  14169.                     the cursor is backtabbed out of it.
  14170.  
  14171.      Examples:
  14172.           SYSMODE BTAB SET
  14173.           SYSMODE BTAB RESET
  14174.  
  14175.      Syntax 2:      SYSMODE LPCHK <SET  or RESET>
  14176.  
  14177.      SET            On LPCHK SET the system level list device error, not the
  14178.                     Q-PRO 4 generated error, will be displayed on the screen on
  14179.                     a list device error.  This is very useful if you are
  14180.                     redirecting the output to a device other than the parallel
  14181.                     printer, so that Q-PRO 4 will not check the status.  If you
  14182.                     don't have LPCHK SET and go to the serial printer, Q-PRO 4
  14183.                     may report the printer not ready.  
  14184.      RESET          On LPCHK RESET, the Q-PRO 4 error will be displayed.  This
  14185.                     is the default mode.
  14186.      Remarks        A single SYSMODE statement can use either BTAB or LPCHK but
  14187.                     not both.  LPCHK is used for DOS and MS-DOS only.Use
  14188.                     separate SYSMODE statements for each one.
  14189.  
  14190.  
  14191.  
  14192.  
  14193.  
  14194.  
  14195.  
  14196.  
  14197.  
  14198.  
  14199.  
  14200.  
  14201.  
  14202.  
  14203.  
  14204.  
  14205.  
  14206.                                        Commands
  14207.                                        Page 223
  14208.  
  14209.  
  14210.  
  14211.  
  14212.  
  14213.  
  14214.  
  14215.                                   Q - PRO 4 Commands
  14216.  
  14217.  
  14218.      SYSTEM
  14219.      ------
  14220.      The SYSTEM command returns control to the operating system.
  14221.  
  14222.      Syntax:   SYSTEM 
  14223.  
  14224.      Remarks        If the FORMLOAD flag was set, control will then be passed to
  14225.                     the format builder utility.
  14226.  
  14227.      Example:
  14228.           SYSTEM
  14229.  
  14230.  
  14231.  
  14232.  
  14233.  
  14234.  
  14235.  
  14236.  
  14237.  
  14238.  
  14239.  
  14240.  
  14241.  
  14242.  
  14243.  
  14244.  
  14245.  
  14246.  
  14247.  
  14248.  
  14249.  
  14250.  
  14251.  
  14252.  
  14253.  
  14254.  
  14255.  
  14256.  
  14257.  
  14258.  
  14259.  
  14260.  
  14261.  
  14262.  
  14263.  
  14264.  
  14265.  
  14266.                                        Commands
  14267.                                        Page 224
  14268.  
  14269.  
  14270.  
  14271.  
  14272.  
  14273.  
  14274.  
  14275.                                   Q - PRO 4 Commands
  14276.  
  14277.  
  14278.      TABLE
  14279.      -----
  14280.      The TABLE statement denotes the start of a data table.
  14281.  
  14282.      Syntax:        TABLE <table name>
  14283.  
  14284.      table name     The name of table as a literal without quotes.
  14285.      Remarks        See the Programmer's Reference Manual for more detail on
  14286.                     handling tables.
  14287.  
  14288.      Example:
  14289.           TABLE STATES
  14290.           "PA"
  14291.           "NJ"
  14292.           "NY"
  14293.           "DE"
  14294.           END
  14295.  
  14296.      TABLE CUSTTYPE
  14297.           0,  "DEADBEAT"
  14298.           1,  "OEM"
  14299.           2,  "DIST."
  14300.           3,  "RETAILER"
  14301.           END
  14302.  
  14303.      TABLE PROCS
  14304.           PROCA
  14305.           PROCB
  14306.           PROCC
  14307.           END
  14308.  
  14309.      TABLE LABELS
  14310.           100
  14311.           200
  14312.           300
  14313.           END
  14314.  
  14315.  
  14316.  
  14317.  
  14318.  
  14319.  
  14320.  
  14321.  
  14322.  
  14323.  
  14324.  
  14325.  
  14326.                                        Commands
  14327.                                        Page 225
  14328.  
  14329.  
  14330.  
  14331.  
  14332.  
  14333.  
  14334.  
  14335.                                   Q - PRO 4 Commands
  14336.  
  14337.  
  14338.      TRACE
  14339.      -----
  14340.      The runtime execution of a program may monitored by executing the TRACE
  14341.      command.
  14342.  
  14343.      Syntax:   TRACE
  14344.  
  14345.      Remarks             Trace places the system into a "debugging" mode.  In
  14346.                          this mode, each statement is displayed on the last line
  14347.                          of the screen just before its execution.  When the user
  14348.                          presses the ESC key, the statement is executed.  This
  14349.                          allows the user to single-step through sections of
  14350.                          code.
  14351.  
  14352.                          Trace mode is turned off by the NOTRACE statement or by
  14353.                          pressing the RETURN key instead of the ESC key.  When
  14354.                          TRACE is on, pressing "D" instead of ESC will invoke
  14355.                          DEBUG after the execution of the instruction displayed
  14356.                          on the screen.
  14357.  
  14358.  
  14359.  
  14360.  
  14361.  
  14362.  
  14363.  
  14364.  
  14365.  
  14366.  
  14367.  
  14368.  
  14369.  
  14370.  
  14371.  
  14372.  
  14373.  
  14374.  
  14375.  
  14376.  
  14377.  
  14378.  
  14379.  
  14380.  
  14381.  
  14382.  
  14383.  
  14384.  
  14385.  
  14386.                                        Commands
  14387.                                        Page 226
  14388.  
  14389.  
  14390.  
  14391.  
  14392.  
  14393.  
  14394.  
  14395.                                   Q - PRO 4 Commands
  14396.  
  14397.  
  14398.      TSEAR
  14399.      -----
  14400.      The TSEAR command allows the search of a table and, optionally, the
  14401.      extraction of data from the table once a if a match for the search argument
  14402.      is found in the first column of the table.
  14403.  
  14404.      Syntax:   TSEAR <table name> AT <key> {,<data item list>} {:error}
  14405.  
  14406.      table name          The name of the table to be searched.
  14407.      key                 The data item which will be compared to the first
  14408.                          element of each line of the table for an exact match. 
  14409.                          To achieve a match, the types of the two keys must be
  14410.                          compatible (string-string or numeric-numeric). If a
  14411.                          match is not found after the first element of every
  14412.                          line is compared, the error branch is taken.
  14413.      data item list      If a match is found, then an item by item data trans-
  14414.                          ferral occurs from the data on the rest of the table
  14415.                          line.
  14416.      Remarks             The TSEAR command can also be used without the data
  14417.                          item list simply to verify the acceptability of an
  14418.                          entry for special codes, etc.  Note that a table used
  14419.                          for indexed procedures or labels cannot be used for the
  14420.                          TSEAR command, since they do not contain a key for
  14421.                          searching.  Refer to Programmer's Reference Manual for
  14422.                          a more complete discussion of table usage.
  14423.  
  14424.  
  14425.      Examples:
  14426.           TSEAR CODETBL AT USERCODE,USERTYPE :100
  14427.                Searches the table CODETBL with the argument in the field (or
  14428.                variable) USERCODE.  If there is a match in the first column of
  14429.                the table and USERCODE, the next element of the table will be
  14430.                placed in the field (or variable) USERTYPE.  If there is no match
  14431.                in the first column of the table with the contents of USERCODE,
  14432.                control goes to 100.
  14433.  
  14434.           TSEAR TRANTBL AT TRANCODE :1023
  14435.  
  14436.  
  14437.  
  14438.  
  14439.  
  14440.  
  14441.  
  14442.  
  14443.  
  14444.  
  14445.  
  14446.                                        Commands
  14447.                                        Page 227
  14448.  
  14449.  
  14450.  
  14451.  
  14452.  
  14453.  
  14454.  
  14455.                                   Q - PRO 4 Commands
  14456.  
  14457.  
  14458.      UCASE
  14459.      -----
  14460.      UCASE forces a string data item to upper case.
  14461.  
  14462.      Syntax:   UCASE <data item>
  14463.  
  14464.      data item           This must be a string data item.
  14465.  
  14466.      Example:
  14467.           UCASE #S5
  14468.           UCASE NAME
  14469.  
  14470.  
  14471.  
  14472.  
  14473.  
  14474.  
  14475.  
  14476.  
  14477.  
  14478.  
  14479.  
  14480.  
  14481.  
  14482.  
  14483.  
  14484.  
  14485.  
  14486.  
  14487.  
  14488.  
  14489.  
  14490.  
  14491.  
  14492.  
  14493.  
  14494.  
  14495.  
  14496.  
  14497.  
  14498.  
  14499.  
  14500.  
  14501.  
  14502.  
  14503.  
  14504.  
  14505.  
  14506.                                        Commands
  14507.                                        Page 228
  14508.  
  14509.  
  14510.  
  14511.  
  14512.  
  14513.  
  14514.  
  14515.                                   Q - PRO 4 Commands
  14516.  
  14517.  
  14518.      UNEDIT
  14519.      ------
  14520.      UNEDIT removes editing characters from a string field such as dollar sign
  14521.      ($) and comma (,) which usually have been placed there by the EDIT command.
  14522.  
  14523.      Syntax:   UNEDIT <string data item> INTO <data item>
  14524.  
  14525.      string data item    The string data item to be UNEDITed.
  14526.      data item           Where the UNEDITED data will be placed.
  14527.  
  14528.      Example:
  14529.           UNEDIT FIELD INTO #N1
  14530.  
  14531.  
  14532.  
  14533.  
  14534.  
  14535.  
  14536.  
  14537.  
  14538.  
  14539.  
  14540.  
  14541.  
  14542.  
  14543.  
  14544.  
  14545.  
  14546.  
  14547.  
  14548.  
  14549.  
  14550.  
  14551.  
  14552.  
  14553.  
  14554.  
  14555.  
  14556.  
  14557.  
  14558.  
  14559.  
  14560.  
  14561.  
  14562.  
  14563.  
  14564.  
  14565.  
  14566.                                        Commands
  14567.                                        Page 229
  14568.  
  14569.  
  14570.  
  14571.  
  14572.  
  14573.  
  14574.  
  14575.                                   Q - PRO 4 Commands
  14576.  
  14577.  
  14578.      UNLOCK
  14579.      ------
  14580.      The UNLOCK command unlocks a previously locked field, and makes it
  14581.      available for operator entry again.
  14582.  
  14583.      Syntax:   UNLOCK <screen data field name or *>
  14584.  
  14585.      screen data field or *   The name of the screen data field to unlock or a
  14586.                               $FIELD function.  If * is used instead of a
  14587.                               specific screen field name, all locked fields are
  14588.                               unlocked.
  14589.  
  14590.      Examples:
  14591.           UNLOCK DATE
  14592.           UNLOCK *
  14593.  
  14594.  
  14595.  
  14596.  
  14597.  
  14598.  
  14599.  
  14600.  
  14601.  
  14602.  
  14603.  
  14604.  
  14605.  
  14606.  
  14607.  
  14608.  
  14609.  
  14610.  
  14611.  
  14612.  
  14613.  
  14614.  
  14615.  
  14616.  
  14617.  
  14618.  
  14619.  
  14620.  
  14621.  
  14622.  
  14623.  
  14624.  
  14625.  
  14626.                                        Commands
  14627.                                        Page 230
  14628.  
  14629.  
  14630.  
  14631.  
  14632.  
  14633.  
  14634.  
  14635.                                   Q - PRO 4 Commands
  14636.  
  14637.  
  14638.      VRBL
  14639.      ----
  14640.      The VRBL statement establishes in-memory variables which can be used in
  14641.      exactly the same manner as screen fields, except that as their value
  14642.      changes, no change is made to the screen display.
  14643.  
  14644.      Syntax:   VRBL <name>, <type>, <length> {,<dimension>}  
  14645.  
  14646.      name           Any alphanumeric data item conforming to the Q-PRO 4 naming
  14647.                     conventions.  The name must not already be in use for
  14648.                     another variable or field.
  14649.      type           Must be an X (for string) or N (for numeric).   Note that
  14650.                     both types of variables are stored in ASCII format, enabling
  14651.                     both string and numeric types of operations on numeric
  14652.                     variables, depending on the statement involved.
  14653.      length         From 1 to 255 characters long for string variables, and from
  14654.                     1 to 20 for numeric variables.
  14655.      dimension      Specifies how many elements of <length> size will be
  14656.                     established.  The default dimension is 1.  The given
  14657.                     dimension may be from 1 to 65,000. 
  14658.  
  14659.      Remarks        Undimensioned variables are referenced exactly like fields,
  14660.                     that is, directly by name.  Dimensioned variables are
  14661.                     referenced by name and element number within brackets.  The
  14662.                     element number may be any numeric expression from 0 to the
  14663.                     number of elements minus 1.
  14664.       
  14665.                     The ideal place to declare variables is in PROC LOAD, since
  14666.                     variables must be declared, may only be declared once, and
  14667.                     are not retained across a CHAIN operation.
  14668.  
  14669.      Examples:
  14670.           VRBL PETE,  X, 10
  14671.                10-character string
  14672.  
  14673.           VRBL FIVE , N, 5, 20
  14674.                20 element array of 5-character numerics
  14675.  
  14676.  
  14677.           VRBL I, N, 4
  14678.           VRBL SARY, X, 80, 12
  14679.                .
  14680.           FOR I=0 TO 11
  14681.                MOVE "" TO SARY[I]
  14682.           ENDFOR I
  14683.                Clear the contents of a string array, using a variable as a loop
  14684.  
  14685.  
  14686.                                        Commands
  14687.                                        Page 231
  14688.  
  14689.  
  14690.  
  14691.  
  14692.  
  14693.  
  14694.  
  14695.                                   Q - PRO 4 Commands
  14696.  
  14697.  
  14698.                counter.
  14699.      WRITE
  14700.      -----
  14701.      WRITE outputs a data record to a file or issues a carriage return line feed
  14702.      to the printer.
  14703.  
  14704.      Syntax:   WRITE <file number> {NOADV} {:error}
  14705.  
  14706.      file number         The file number of the record to be written.
  14707.      NOADV               If the NOADV keyword is given (for random and indexed
  14708.                          files only), the record position in the file is not
  14709.                          advanced.  Otherwise, the record positioned is advanced
  14710.                          to the next position in the file.  Using NOADV whenever
  14711.                          possible will provide optimal record access time.
  14712.  
  14713.           Actions of WRITE With Various File Types
  14714.           ----------------------------------------
  14715.  
  14716.           Sequential files
  14717.                A data record is written and terminated by a carriage return/line
  14718.                feed sequence.
  14719.  
  14720.           Random files
  14721.                The record is written to the current position of the file.
  14722.  
  14723.           Indexed files
  14724.                The record is written to the position defined by the key of the
  14725.                record.  A POSN command before an indexed file write is therefore
  14726.                both unnecessary and wasteful.
  14727.  
  14728.           List device
  14729.                If the file number is 0, then a carriage return/line feed
  14730.                sequence is output to the list device.  The line number register
  14731.                (#L) will then be incremented automatically.
  14732.  
  14733.  
  14734.  
  14735.      Examples:
  14736.           WRITE 0
  14737.           WRITE 1 NOADV :122
  14738.  
  14739.  
  14740.  
  14741.  
  14742.  
  14743.  
  14744.  
  14745.  
  14746.                                        Commands
  14747.                                        Page 232
  14748.  
  14749.  
  14750.  
  14751.  
  14752.  
  14753.  
  14754.  
  14755.                                   Q - PRO 4 Commands
  14756.  
  14757.  
  14758.                        Q - P R O 4  E R R O R   M E S S A G E S
  14759.                        ========================================
  14760.  
  14761.                                    Trappable Errors
  14762.                                    ================
  14763.  
  14764.      #N0 Value           Message
  14765.      ---------           --------
  14766.            1        BAD DATA IN FIELD
  14767.            2        BAD SIGNED RESULT
  14768.            3        BAD OPERAND
  14769.            4        ARITHMETIC OVERFLOW
  14770.            5        NO TABLE MATCH
  14771.            6        FILE UNAVAILABLE
  14772.            7        FILE NOT OPEN
  14773.            8        BUFFER OVERFLOW
  14774.            9        OUTPUT FILE ONLY
  14775.           10        END OF RECORD
  14776.           11        END OF FILE
  14777.           12        INPUT FILE ONLY
  14778.           13        BAD DEST. START
  14779.           14        BAD REC POSN
  14780.           15        BAD INDEXED FILE
  14781.           16        NO SUCH FILE
  14782.           17        BAD FORMAT DESCRIPTOR
  14783.           18        NO DATA IN BUFFER
  14784.           19        BAD FILE NAME
  14785.           20        DISK IO ERROR
  14786.           21        NO FID FILE
  14787.           22        BAD FID FILE
  14788.           23        BAD FID ITEM INDEX
  14789.           24        MEMORY OVERFLOW ON MEMEND
  14790.           25        FILE EXCLUSION LOCK FAILED
  14791.           26        FILE SYNCH. FAILURE
  14792.           27        BAD HOST STATEMENT
  14793.           28        FILE READ ONLY
  14794.           29        EXEC ERROR
  14795.           30        LINE PRINTER ERROR (16 bit only)
  14796.           31        MATHLIB (8 bit only)
  14797.           33        FILE SYSTEM NOT LOADED
  14798.           34        DELETED RECORD READ
  14799.  
  14800.  
  14801.  
  14802.  
  14803.  
  14804.  
  14805.  
  14806.                                     Error Messages
  14807.                                        Page 233
  14808.  
  14809.  
  14810.  
  14811.  
  14812.  
  14813.  
  14814.  
  14815.                                   Q - PRO 4 Commands
  14816.  
  14817.  
  14818.                                   Error Codes for #E
  14819.                                   ------------------
  14820.  
  14821.      Error numbers found in #E under DOS are interpreted as follows:
  14822.  
  14823.           #E Value            Message
  14824.           --------         -----------
  14825.                 1        data file open
  14826.                 2        data file creation error
  14827.                 3        data file read error
  14828.                 4        data file write error
  14829.                 5        data close error
  14830.                 6        FID file open
  14831.                 7        FID file read error
  14832.                 8        FID file wrong version
  14833.                 9        Out of memory
  14834.                10        Index file error
  14835.                11        Error during handle reuse
  14836.                12        error during file system initialization
  14837.                13        data file less than the minimum length (8 characters)
  14838.                14        Unable to unlock record
  14839.                15        (reserved)
  14840.                16        Maximum indices exceeded (100 allowed)
  14841.                17        Not enough handles
  14842.                18        Activity tried on inactive file.
  14843.               100        End of file
  14844.               101        (Reserved)
  14845.               102        Illegal function on file (deleting a random record)
  14846.               103        Deleting a record before a read
  14847.               104        (Reserved)
  14848.               105        File read only
  14849.               106        Bad host value
  14850.               107        Record locked
  14851.               108        Header busy (try again)
  14852.               109        Deleted record read
  14853.               110        Bad key description list
  14854.  
  14855.  
  14856.  
  14857.  
  14858.  
  14859.  
  14860.  
  14861.  
  14862.  
  14863.  
  14864.  
  14865.  
  14866.                                     Error Messages
  14867.                                        Page 234
  14868.  
  14869.  
  14870.  
  14871.  
  14872.  
  14873.  
  14874.  
  14875.                                   Q - PRO 4 Commands
  14876.  
  14877.  
  14878.                          Cross Reference of Trappable Errors
  14879.                          ===================================
  14880.  
  14881.                           #N0                 #E
  14882.           Value          Error               Value
  14883.           ---------------------------------------
  14884.            6        File unavailable         1,2
  14885.           11        End of file              100
  14886.           18        No data in buffer        103
  14887.           21        No FID file                6
  14888.           22        Bad FID file             7,8
  14889.           24        Memory overflow            9
  14890.           25        File exclusion lock      107, 108
  14891.           27        Bad host statement       106
  14892.            8        File read only           105
  14893.           34        Deleted record read      109
  14894.           20        All other disk I/O errors  3
  14895.  
  14896.  
  14897.  
  14898.                                      BTSYS Errors
  14899.                                      ============
  14900.  
  14901.      These errors are reported as "C-Tree" errors.
  14902.  
  14903.           Error Number              Description
  14904.                231       A data file index is so corrupted that the file handler
  14905.                          cannot proceed any further.  The only recover is using
  14906.                          QMAINT to recover the file.
  14907.  
  14908.                230       This is a different error with the same cause and
  14909.                          solution as the one above.
  14910.  
  14911.       
  14912.  
  14913.  
  14914.  
  14915.  
  14916.  
  14917.  
  14918.  
  14919.  
  14920.  
  14921.  
  14922.  
  14923.  
  14924.  
  14925.  
  14926.                                     Error Messages
  14927.                                        Page 235
  14928.  
  14929.  
  14930.  
  14931.  
  14932.  
  14933.  
  14934.  
  14935.                                   Q - PRO 4 Commands
  14936.  
  14937.  
  14938.                               Error Message Descriptions
  14939.                               ==========================
  14940.  
  14941.      The following is a complete list of error messages generated by the Q-PRO 4
  14942.      system (in programs FB and QNE). Certain of the error messages generated by
  14943.      the run-time system (QNE) are either recoverable by the operator (by
  14944.      pressing ESCAPE), or are programmatically trappable. Otherwise, all
  14945.      run-time errors are fatal.
  14946.  
  14947.      , EXPECTED
  14948.      Statement syntax requires a comma.
  14949.  
  14950.      = EXPECTED
  14951.      Statement syntax required an equals sign, and there was none.
  14952.  
  14953.      " EXPECTED
  14954.      Statement contains unbalanced quotes.
  14955.  
  14956.      ] EXPECTED
  14957.      Statement contains unbalanced brackets.
  14958.  
  14959.      [ EXPECTED
  14960.      Statement syntax requires a left bracket, and none was found.
  14961.  
  14962.      ARITHMETIC OVERFLOW
  14963.      Attempt made to perform invalid calculation (such as divide by zero).
  14964.      Trappable globally as error 4.
  14965.  
  14966.      AT EXPECTED
  14967.      Statement syntax requires the keyword "at".
  14968.  
  14969.      BAD BUFFER SIZE
  14970.      An invalid value (greater than 255) as given as the keyboard buffer size in
  14971.      a BUFFER statement.
  14972.  
  14973.      BAD COMMAND STRING
  14974.      An invalid command string was given in a SYSTEM command.
  14975.  
  14976.      BAD CONDITION
  14977.      Unrecognizable condition in IF statement, or attempted to compare a number
  14978.      to a string.
  14979.  
  14980.      BAD DATA IN FIELD
  14981.      Non-numeric data exists in field (usually put there programmatically). 
  14982.      Trappable globally as error 1.
  14983.  
  14984.  
  14985.  
  14986.                                     Error Messages
  14987.                                        Page 236
  14988.  
  14989.  
  14990.  
  14991.  
  14992.  
  14993.  
  14994.  
  14995.                                   Q - PRO 4 Commands
  14996.  
  14997.  
  14998.  
  14999.      BAD DEST. START
  15000.      Program attempted a partial move from past the end of a string. Trappable
  15001.      globally as error 13.
  15002.  
  15003.      BAD EXPRESSION
  15004.      Statement contained an invalid arithmetic expression.
  15005.  
  15006.      BAD FID FILE
  15007.      An invalid file was attempted for use as a fid file.
  15008.  
  15009.      BAD FID ITEM INDEX
  15010.      An out-of-range value was given for a fid field index.
  15011.  
  15012.      BAD FIELD FILL
  15013.      Numeric calculation not possible with a numeric field whose fill character
  15014.      is other that a blank or a digit.
  15015.  
  15016.      BAD FILE FORMAT
  15017.      Locked file format was not correct.
  15018.  
  15019.      BAD FILE NAME
  15020.      Program attempted to OPEN or MAKE a file with an invalid given name. 
  15021.      Trappable locally in OPEN and MAKE.  Trappable globally as error 19.
  15022.  
  15023.      BAD FILE NUMBER
  15024.      Program attempted to OPEN or MAKE a file with a number less than 1 or
  15025.      greater than 255.
  15026.  
  15027.      BAD FILE TYPE
  15028.      Program attempted to OPEN or MAKE a file with a type not in the range 0-5.
  15029.  
  15030.      BAD FLAG REGISTER REFERENCE
  15031.      Flag register reference expected.
  15032.  
  15033.      BAD FORMAT DESCRIPTOR
  15034.      Program attempted to EDIT a numeric data item with an invalid descriptor. 
  15035.      Trappable locally in EDIT. Trappable globally as error 17.
  15036.  
  15037.      BAD FUNCTION KEY
  15038.      Undefined or non-numeric function (escape) key sequence was pressed. 
  15039.      Recoverable.
  15040.  
  15041.      BAD HOST STATEMENT
  15042.      A host statement was executed which either did not have a recognizable name
  15043.      or at a time when all files were not closed.  Trappable as error 27.
  15044.  
  15045.  
  15046.                                     Error Messages
  15047.                                        Page 237
  15048.  
  15049.  
  15050.  
  15051.  
  15052.  
  15053.  
  15054.  
  15055.                                   Q - PRO 4 Commands
  15056.  
  15057.  
  15058.  
  15059.  
  15060.      BAD INDEXED 
  15061.      Program attempted to OPEN a file with an invalid internal format as an
  15062.      indexed file. Trappable locally in OPEN.  Trappable globally as error 15.
  15063.  
  15064.      BAD INDEX LENGTH
  15065.      Program attempted to MAKE a file whose index length takes the key out of
  15066.      the first 128 bytes of the data record.
  15067.  
  15068.      BAD INDEX START 
  15069.      Program attempted to MAKE a file whose index start was greater than 128.
  15070.  
  15071.      BAD KEYSTROKE IN FIELD
  15072.      Operator keyed an invalid character for the field type.  Recoverable.
  15073.  
  15074.      BAD MODIFIER
  15075.      Invalid string starting position in MOVE modifier.
  15076.  
  15077.      BAD OPERAND
  15078.      Program attempted to store into an invalid data item. Trappable globally as
  15079.      error 3.
  15080.  
  15081.      BAD PROC FORMAT
  15082.      Illegal PROC statement.
  15083.  
  15084.      BAD PROC NAME IN FILE
  15085.      Program contains an invalid or missing procedure reference.
  15086.  
  15087.      BAD REC POSN
  15088.      Invalid value given for a record number.  Trappable locally in POSN. 
  15089.      Trappable globally as error 14.
  15090.  
  15091.      BAD REC SIZE
  15092.      Record size may not be 0.
  15093.  
  15094.      BAD REGISTER
  15095.      Program attempted to do a modified MOVE from a numeric register.
  15096.  
  15097.      BAD SIGNED RESULT
  15098.      Program attempted to put a negative number in a digit (D descriptor )
  15099.      field. Trappable globally as error 2.
  15100.  
  15101.      BAD STATEMENT
  15102.      Statement is unrecognizable.
  15103.  
  15104.  
  15105.  
  15106.                                     Error Messages
  15107.                                        Page 238
  15108.  
  15109.  
  15110.  
  15111.  
  15112.  
  15113.  
  15114.  
  15115.                                   Q - PRO 4 Commands
  15116.  
  15117.  
  15118.      BAD TABLE NAME IN FILE
  15119.      Program contains an invalid or missing table reference.
  15120.  
  15121.      BAD VRBL DECL
  15122.      Variable declaration contains an invalid parameter.
  15123.  
  15124.      BAD VRBL INDEX
  15125.      Index to a variable array exceeded the maximum value.
  15126.  
  15127.      BUFFER OVERFLOW
  15128.      Program attempted to move a file buffer pointer past the end of the file
  15129.      buffer. Trappable locally in PUT.  Trappable globally as error 8.
  15130.  
  15131.      BY EXPECTED
  15132.      Statement syntax requires the keyword "by".
  15133.  
  15134.      DEMO SYSTEM LIMITS EXCEEDED
  15135.      Program attempted to exceed limitations of the evaluation version of the
  15136.      system.
  15137.  
  15138.      DISK IO ERROR
  15139.      A hardware fault was returned by the operating system after a disk opera-
  15140.      tion.  Trappable locally in any file statement.  Trappable globally as
  15141.      error 20.
  15142.  
  15143.      DUPLICATE FIELD NAME
  15144.      Field name has already been assigned.
  15145.  
  15146.      END OF FILE
  15147.      Program attempted to read past the end of a file.  Trappable locally in GET
  15148.      (for sequential files) and READ (for random/indexed files).  Trappable
  15149.      globally as error 11.
  15150.  
  15151.      END OF RECORD
  15152.      Program attempted to GET past the end of a record.  Trappable locally in
  15153.      GET.  Trappable globally as error 10.
  15154.  
  15155.      EXEC ERROR
  15156.      The programmer has POPPED the normal return from the stack and issued a
  15157.      RETURN.  Trappable globally as error 29.
  15158.  
  15159.      ENDFOR WITHOUT FOR
  15160.      An ENDFOR statement was detected for which there was no corresponding FOR
  15161.      statement.
  15162.  
  15163.      FIELD OUT OF SCREEN RANGE
  15164.  
  15165.  
  15166.                                     Error Messages
  15167.                                        Page 239
  15168.  
  15169.  
  15170.  
  15171.  
  15172.  
  15173.  
  15174.  
  15175.                                   Q - PRO 4 Commands
  15176.  
  15177.  
  15178.      Given field length would exceed screen boundary.
  15179.  
  15180.      FIELD UNAVAILABLE
  15181.      Program attempted to NEXT to a non-enterable field.
  15182.  
  15183.      FILE EXCLUSION LOCK FAILED
  15184.      System tried to lock record 0 of an indexed file. (required for most file
  15185.      operations) and could not get the lock.  Trappable as error 25.
  15186.  
  15187.      FILE LIMITS OVERRUN
  15188.      An attempt was made to add data to a file already occupying the operating
  15189.      system maximum megabytes of data.
  15190.  
  15191.      FILE NOT OPEN
  15192.      Program failed to OPEN or MAKE file before first I/O reference. Trappable
  15193.      locally in any file statement. Trappable globally as error 7.
  15194.  
  15195.      FILE OPEN
  15196.      Program attempted to OPEN or MAKE a file using an already active file
  15197.      number.
  15198.      FILE READ ONLY
  15199.      Tried to write to a read only file.  Trappable as error 28.
  15200.           
  15201.      FILE SYNCH. FAILURE
  15202.      Files are said to be out of synch when one process reads a record with
  15203.      apparently valid index links, which is then discovered to have been deleted
  15204.      by some other process.  Trappable as error 26.
  15205.  
  15206.      FILE UNAVAILABLE
  15207.      File does not exist. Trappable locally in OPEN. Trappable globally as error
  15208.      6.
  15209.  
  15210.      FOR EXPECTED
  15211.      Statement syntax requires the keyword "FOR".
  15212.  
  15213.      FORMAT LOAD OVERRUN
  15214.      The format file indicated will not fit in memory.
  15215.  
  15216.      FORMAT CREATE ERROR
  15217.      The format file can not be created due to disk error or filled directory.
  15218.  
  15219.      FORMAT MEMORY OVERFLOW
  15220.      No room left in memory for a new field definition.
  15221.  
  15222.      FORMAT WRITE ERROR
  15223.      The format file cannot be saved on disk (I/O error or full disk).
  15224.  
  15225.  
  15226.                                     Error Messages
  15227.                                        Page 240
  15228.  
  15229.  
  15230.  
  15231.  
  15232.  
  15233.  
  15234.  
  15235.                                   Q - PRO 4 Commands
  15236.  
  15237.  
  15238.  
  15239.      FROM EXPECTED
  15240.      Statement syntax requires the keyword "from".
  15241.  
  15242.      INCONSISTENT "MAY ENTER" ENTER">
  15243.      The given MAY ENTER value does not agree with the given MUST ENTER value
  15244.      (if MUST ENTER is Y, then MAY ENTER must be Y as well).
  15245.  
  15246.      INPUT FILE ONLY
  15247.      Program attempted to write to an input sequential file. Trappable locally
  15248.      in PUT or WRITE. Trappable globally as error 12.
  15249.  
  15250.      INTO EXPECTED
  15251.      Statement syntax requires the keyword "into".
  15252.      INVALID DESCRIPTOR TYPE
  15253.      Field descriptor was an invalid character.
  15254.  
  15255.      INVALID FIELD LENGTH
  15256.      The given field length was zero, or non-numeric.
  15257.  
  15258.      INVALID FIELD NAME
  15259.      A field name must be maximum ten alphanumeric characters, starting with an
  15260.      alphabetic.
  15261.  
  15262.      INVALID FILE NAME
  15263.      Indicated file name does not obey system rules for an unambiguous file
  15264.      name.
  15265.  
  15266.      INVALID "JUSTIFY"
  15267.      The value for the justification field must be L or R.
  15268.  
  15269.      INVALID PARAGRAPH NUMBER
  15270.      A non-numeric paragraph number was requested.
  15271.  
  15272.      INVALID "MAY ENTER"
  15273.      The value for the may-enter field must be Y or N.
  15274.  
  15275.      INVALID "MUST ENTER"
  15276.      The value for the must-enter field must be Y or N.
  15277.  
  15278.      INVALID "MUST FILL"
  15279.      The value for the must-fill field must be Y or N.
  15280.  
  15281.      INVALID "MUST TAB"
  15282.      The value for the must-tab field must be Y or N.
  15283.  
  15284.  
  15285.  
  15286.                                     Error Messages
  15287.                                        Page 241
  15288.  
  15289.  
  15290.  
  15291.  
  15292.  
  15293.  
  15294.  
  15295.                                   Q - PRO 4 Commands
  15296.  
  15297.  
  15298.      INVALID PROCEDURE NAME
  15299.      A procedure name must be a maximum of ten alphanumeric characters, starting
  15300.      with an alphabetic.
  15301.  
  15302.      INVALID SELECTION
  15303.      A non-existent or non-numeric selection was made from the main menu.
  15304.  
  15305.      INVALID X COORDINATE
  15306.      Given row coordinate is non-numeric, or exceeds the length of the screen.
  15307.      INVALID Y COORDINATE
  15308.      Given column coordinate is non-numeric, or exceeds the width of the screen.
  15309.      LINE PRINTER ERROR
  15310.      Printer not ready.  Trappable globally as error 30.
  15311.  
  15312.      MATHLIB NOT LOADED
  15313.      (8 bit only)  Attempted to use $LN, $ETOX, $INT, or exponentiation without
  15314.      MATHLIB loaded.  Trappable globally as error 31.
  15315.  
  15316.      MEMORY OVERFLOW
  15317.      Format file will not fit in available memory, or there is no space to open
  15318.      a new file, or no space to allocate a new variable, or expression required
  15319.      too much temporary storage to execute.
  15320.  
  15321.      MISSING FILE NAME
  15322.      Statement syntax requires a file name.
  15323.  
  15324.      MUST ENTER FIELD
  15325.      Operator attempted to exit a field without entering any data.  Recoverable.
  15326.  
  15327.      MUST FILL FIELD
  15328.      Operator attempted to exit a field without filling it.  Recoverable.
  15329.  
  15330.      NEW FILE
  15331.      The given file name does not exist; it will be created at file save time.
  15332.  
  15333.      NO DATA IN BUFFER
  15334.      Program attempted to delete an indexed record without first loading the
  15335.      record. Trappable locally in FREE.  Trappable globally as error 18.
  15336.  
  15337.      NO ENTERABLE FIELDS
  15338.      Format file contains no enterable fields.
  15339.  
  15340.      NO FILE
  15341.      Attempted to initially load a non-existent format file.
  15342.  
  15343.      NO FORMAT DEFINED
  15344.  
  15345.  
  15346.                                     Error Messages
  15347.                                        Page 242
  15348.  
  15349.  
  15350.  
  15351.  
  15352.  
  15353.  
  15354.  
  15355.                                   Q - PRO 4 Commands
  15356.  
  15357.  
  15358.      The indicated menu selection requires the previous selection of main menu
  15359.      choice N.
  15360.  
  15361.      NO FID FILE
  15362.      A fid file was named in an OPEN or MAKE statement which does not exist.
  15363.  
  15364.      NO MORE ROOM FOR PARAGRAPH
  15365.      Updating the indicated paragraph would exceed memory space.
  15366.  
  15367.      NON-NUMERIC FIELD
  15368.      Program attempted to perform arithmetic with non-numeric data.
  15369.  
  15370.      NO SUCH FILE
  15371.      Program attempted to CHAIN to a non-existent file. Trappable globally as
  15372.      error 16.
  15373.  
  15374.      NO SUCH TABLE
  15375.      Program referenced a non-existent table.
  15376.  
  15377.      NO SUCH FIELD OR VRBL
  15378.      Referenced field or variable does not exist.
  15379.  
  15380.      NO SUCH LABEL
  15381.      Referenced label does not exist.
  15382.  
  15383.      NO TABLE MATCH
  15384.      Program executed a TSEAR statement that resulted in no match being found.
  15385.      Trappable locally in TSEAR. Trappable globally as error 5.
  15386.  
  15387.      OUTPUT FILE ONLY
  15388.      Program attempted to GET or READ an output sequential file. Trappable
  15389.      locally in GET and READ.  Trappable globally as error 9.
  15390.  
  15391.      RECURSIVE ERROR
  15392.      An error in closing a file caused the system to go into termination logic,
  15393.      which also attempts to close the file. Rather than hang up in an infinite
  15394.      attempt to deal with the offending file, this error message is displayed
  15395.      and QNE reboots directly.
  15396.  
  15397.      RETURN WITHOUT CALL
  15398.      Program attempted to RETURN without a corresponding CALL.
  15399.  
  15400.      STACK OVERFLOW
  15401.      Program executed too many nested CALL statements.
  15402.  
  15403.      TO EXPECTED
  15404.  
  15405.  
  15406.                                     Error Messages
  15407.                                        Page 243
  15408.  
  15409.  
  15410.  
  15411.  
  15412.  
  15413.  
  15414.  
  15415.                                   Q - PRO 4 Commands
  15416.  
  15417.  
  15418.      Statement syntax requires the keyword "to".
  15419.  
  15420.      USING EXPECTED
  15421.      Statement syntax requires the keyword "using".
  15422.  
  15423.      WHAT?
  15424.      User attempted to load a non-format file for editing.
  15425.  
  15426.  
  15427.  
  15428.  
  15429.  
  15430.  
  15431.  
  15432.  
  15433.  
  15434.  
  15435.  
  15436.  
  15437.  
  15438.  
  15439.  
  15440.  
  15441.  
  15442.  
  15443.  
  15444.  
  15445.  
  15446.  
  15447.  
  15448.  
  15449.  
  15450.  
  15451.  
  15452.  
  15453.  
  15454.  
  15455.  
  15456.  
  15457.  
  15458.  
  15459.  
  15460.  
  15461.  
  15462.  
  15463.  
  15464.  
  15465.  
  15466.                                     Error Messages
  15467.                                        Page 244
  15468.  
  15469.  
  15470.  
  15471.  
  15472.  
  15473.  
  15474.  
  15475.                                   Q - PRO 4 Commands
  15476.  
  15477.  
  15478.                                         QMAINT
  15479.                                         ======
  15480.  
  15481.      Overview
  15482.      --------
  15483.      QMAINT.EXE packs, verifies or recovers an indexed file.  QMAINT may be run
  15484.      from the command line with prompting or the entire command with parameters
  15485.      may be typed from the command line or executed from a RUN command or a .BAT
  15486.      file.  Under MS-DOS and PC-DOS, the full 64 character file names may be
  15487.      used.
  15488.  
  15489.      Prompted Execution
  15490.      ------------------
  15491.      Typing QMAINT on the command line followed by a Return will display this
  15492.      prompt:
  15493.  
  15494.           File Maintenance Utility
  15495.           Copyright (c) QNE International, 1985
  15496.  
  15497.      Menu selections are:
  15498.  
  15499.      1 - PACK
  15500.           Pack compresses the index file.  It is never mandatory to run PACK but
  15501.           if the indexed data file has a large number of deleted records, PACK
  15502.           will reclaim the space in the index file.  This will reduce the size
  15503.           of the index file.  PACK creates a temporary file and copies the file
  15504.           to be packed to it.  After a successful pack the original index file
  15505.           will be erased and the packed file renamed to the original.
  15506.  
  15507.      2 - VERIFY
  15508.           Verify checks the data file and the index file for validity.  This
  15509.           utility should be run if the indexed data file is suspected of being
  15510.           corrupted.  If there is any error message during the execution, then
  15511.           the file should be RECOVERed.  Verify does not use any disk space.  
  15512.           Verify rebuilds the deleted record chain as it goes, automatically.
  15513.  
  15514.      3 - RECOVER
  15515.           Recover restores a data file's index to a usable condition.  Note that
  15516.           index files get corrupted, not data files.  Most of the time corrup-
  15517.           tion of an index file can be traced to one of the following causes:
  15518.  
  15519.      o    The user turning off the machine before the files are closed.
  15520.      o    Trying to use the same index file for two data files.
  15521.      o    Miscellaneous hardware, power and operating software problems.      
  15522.  
  15523.      First the old index file is erased first and then a new one is built.
  15524.  
  15525.  
  15526.                                       Utilities
  15527.                                        Page 245
  15528.  
  15529.  
  15530.  
  15531.  
  15532.  
  15533.  
  15534.  
  15535.                                   Q - PRO 4 Commands
  15536.  
  15537.  
  15538.  
  15539.      X - Exit
  15540.      --------
  15541.      Return to operating system.
  15542.  
  15543.      Making any menu selection, except X, will display these prompts:
  15544.  
  15545.      Please enter data file name        Type the name of the data file and its
  15546.                                         extension followed by a Return.
  15547.  
  15548.      Please enter IDX file name:        Type the name of the index file and its
  15549.                                         extension.  If the name of the index
  15550.                                         file is the same as the data file and
  15551.                                         only the extension is different, you may
  15552.                                         omit the index file name and press
  15553.                                         Return.  QMAINT will assume that the
  15554.                                         index file is the same name as the data
  15555.                                         file with the extension "FID".
  15556.  
  15557.      Please enter FID file name:        Type the name of the FID file including
  15558.                                         its extension.  If the name of the FID
  15559.                                         file is the same as the data file and
  15560.                                         only the extension is different, you may
  15561.                                         omit the FID file name and press Return. 
  15562.                                         QMAINT will assume that the index file
  15563.                                         is the same name as the data file with
  15564.                                         the extension "IDX".
  15565.  
  15566.      Please enter options (RESULT,CONTINUE,VERBOSE):
  15567.  
  15568.      The Options are:
  15569.  
  15570.           RESULT    If any of the functions fail the file, QMAINT.BAD, will be
  15571.                     created (but will be empty). If RESULT is not specified and
  15572.                     an error occurs, a return code of 1 will be set when the
  15573.                     program exits (DOS only).  This return code may be used
  15574.                     logically in a DOS BAT file, e.g., "IF NOT ERROR LEVEL 0
  15575.                     GOTO . . . ." (See Batch Processing Commands in DOS 2.0 and
  15576.                     higher manuals.)
  15577.  
  15578.           CONTINUE  used only with VERIFY.  If specified, the verify function
  15579.                     will not stop after a verify error.
  15580.  
  15581.           VERBOSE   Display key values instead of flashing  "WORKING".
  15582.  
  15583.      Select the options desired and press Return.  An appropriate message will
  15584.  
  15585.  
  15586.                                       Utilities
  15587.                                        Page 246
  15588.  
  15589.  
  15590.  
  15591.  
  15592.  
  15593.  
  15594.  
  15595.                                   Q - PRO 4 Commands
  15596.  
  15597.  
  15598.      display.
  15599.  
  15600.      Execution from the Command Line
  15601.      -------------------------------
  15602.      QMAINT may be run from the command line by typing the command in the syntax
  15603.      shown below:
  15604.  
  15605.      QMAINT <function><filename>{parameters}
  15606.  
  15607.      where:
  15608.  
  15609.      <function>          PACK,  VERIFY, or RECOVER
  15610.  
  15611.      <filename>          datafile name \FIDfile name\\INDEX file name.  If the
  15612.                          FID or index file name is omitted, it will be assumed
  15613.                          to be the same as the datafile name with the proper
  15614.                          extensions.
  15615.  
  15616.      <parameters>        Optionally RESULT, CONTINUE, VERBOSE.  These options
  15617.                          are the same as shown above.
  15618.  
  15619.      Execution from the RUN Command or a .BAT file
  15620.      ---------------------------------------------
  15621.      The RUN command and the .BAT file syntax are identical to the command line
  15622.      syntax.
  15623.  
  15624.      Examples:
  15625.      QMAINT PACK data1.dat FID data1.fid INDEX data1.idx VERBOSE
  15626.           PACK a file named DATA1.DAT whose FID file is DATA1.FID and whose
  15627.           index file is DATA1.IDX and display the activity as it occurs.
  15628.  
  15629.      Note that the FID file name is preceded with the keyword "FID" and the
  15630.      index file name is preceded with the keyword "INDEX".
  15631.  
  15632.      QMAINT PACK DATA1.DAT VERBOSE
  15633.           VERIFY a file named DATA1.DAT whose FID file is DATA1.FID and whose
  15634.           index file is DATA1.IDX.  If verify fails create the file QMAINT.BAD. 
  15635.           If verify fails, continue with the verification.  Display the activity
  15636.           as it occurs.
  15637.  
  15638.      QMAINT VERIFY data1.dat FID data1.fid INDEX data1.idx RESULT, CONTINUE,    
  15639.         VERBOSE
  15640.      or
  15641.  
  15642.      QMAINT VERIFY DATA1.DAT RESULT,CONTINUE,VERBOSE
  15643.  
  15644.  
  15645.  
  15646.                                       Utilities
  15647.                                        Page 247
  15648.  
  15649.  
  15650.  
  15651.  
  15652.  
  15653.  
  15654.  
  15655.                                   Q - PRO 4 Commands
  15656.  
  15657.  
  15658.                           Q N E   I N T E R N A T I O N A L
  15659.  
  15660.                                       Order Form
  15661.  
  15662.      Please send:
  15663.  
  15664.      ___ Copies of Q-PRO 4 at $50.00 each                   __________
  15665.      ___ Copies of Q-PRO 4 Plus $90.00 each                 __________
  15666.      ___ Copies of Author's LockUp at $150.00 each          __________
  15667.      ___ Report Generator distribution licence at
  15668.           $150.00 each                                      __________
  15669.      ___ Copies of Q2C at $250.00 each                      __________
  15670.      ___ Membership in QNE User's Group at $25.00 each      __________
  15671.      ___ One year of telephone technical support at
  15672.            $150.00 per year                                 __________
  15673.      ___ Q-Query, post relational query language at
  15674.            $50.00 each                                      __________ 
  15675.  
  15676.                               Subtotal                      __________
  15677.  
  15678.      Shipping:(UPS Ground, US $7.00)                        __________
  15679.      Pennsylvania and New Jersey residents please
  15680.           add 6% sales tax                                  __________
  15681.  
  15682.                               Total                        $__________
  15683.       
  15684.                           
  15685.      Name: ______________________________________________________
  15686.  
  15687.      Company: ___________________________________________________
  15688.  
  15689.      Address: ___________________________________________________
  15690.  
  15691.      City: _________________________  State:_____  ZIP:__________
  15692.  
  15693.      Telephone: ______________________  FAX:_____________________
  15694.  
  15695.      Payment by: __MC  __ VISA  __Check
  15696.  
  15697.      Cardnumber __________________________________  Expiration ___/___
  15698.  
  15699.      Signature: _______________________________________________
  15700.  
  15701.      To place your order send this form or call (800)333-0448.
  15702.  
  15703.      Sorry, NO COD's
  15704.  
  15705.  
  15706.                                       Utilities
  15707.                                        Page 248
  15708.